Signed-off-by: Angus Salkeld <asalkeld(a)redhat.com>
---
include/qb/qbipcc.h | 19 +++++++++++++++++++
include/qb/qbipcs.h | 32 ++++++++++++++++++++++++++------
2 files changed, 45 insertions(+), 6 deletions(-)
diff --git a/include/qb/qbipcc.h b/include/qb/qbipcc.h
index a55848f..0a1124f 100644
--- a/include/qb/qbipcc.h
+++ b/include/qb/qbipcc.h
@@ -106,6 +106,10 @@ int32_t qb_ipcc_fc_enable_max_set(qb_ipcc_connection_t * c, uint32_t
max);
* @param msg_ptr pointer to a message to send
* @param msg_len the size of the message
* @return (size sent, -errno == error)
+ *
+ * @note the msg_ptr must include a qb_ipc_request_header at
+ * the top of the message. The server will read the size field
+ * to determine how much to recv.
*/
ssize_t qb_ipcc_send(qb_ipcc_connection_t* c, const void *msg_ptr,
size_t msg_len);
@@ -116,6 +120,9 @@ ssize_t qb_ipcc_send(qb_ipcc_connection_t* c, const void *msg_ptr,
* @param iov pointer to an iovec struct to send
* @param iov_len the number of iovecs used
* @return (size sent, -errno == error)
+ *
+ * @note the iov[0] must be a qb_ipc_request_header. The server will
+ * read the size field to determine how much to recv.
*/
ssize_t qb_ipcc_sendv(qb_ipcc_connection_t* c, const struct iovec* iov,
size_t iov_len);
@@ -127,6 +134,9 @@ ssize_t qb_ipcc_sendv(qb_ipcc_connection_t* c, const struct iovec*
iov,
* @param msg_len the size of the buffer
* @param ms_timeout max time to wait for a response
* @return (size recv'ed, -errno == error)
+ *
+ * @note that msg_ptr will include a qb_ipc_response_header at
+ * the top of the message.
*/
ssize_t qb_ipcc_recv(qb_ipcc_connection_t* c, void *msg_ptr,
size_t msg_len, int32_t ms_timeout);
@@ -141,6 +151,12 @@ ssize_t qb_ipcc_recv(qb_ipcc_connection_t* c, void *msg_ptr,
* @param msg_len the size of the buffer
* @param ms_timeout max time to wait for a response
*
+ * @note the iov[0] must include a qb_ipc_request_header at
+ * the top of the message. The server will read the size field
+ * to determine how much to recv.
+ * @note that msg_ptr will include a qb_ipc_response_header at
+ * the top of the message.
+ *
* @see qb_ipcc_sendv() qb_ipcc_recv()
*/
ssize_t qb_ipcc_sendv_recv(qb_ipcc_connection_t *c,
@@ -158,6 +174,9 @@ ssize_t qb_ipcc_sendv_recv(qb_ipcc_connection_t *c,
* 0 == no wait, negative == block, positive == wait X ms.
* @param ms_timeout max time to wait for a response
* @return size of the message or error (-errno)
+ *
+ * @note that msg_ptr will include a qb_ipc_response_header at
+ * the top of the message.
*/
ssize_t qb_ipcc_event_recv(qb_ipcc_connection_t* c, void *msg_ptr,
size_t msg_len, int32_t ms_timeout);
diff --git a/include/qb/qbipcs.h b/include/qb/qbipcs.h
index c1aeffe..0a4caed 100644
--- a/include/qb/qbipcs.h
+++ b/include/qb/qbipcs.h
@@ -106,7 +106,8 @@ struct qb_ipcs_poll_handlers {
* or process resource constraints.
* @return 0 to accept or -errno to indicate a failure (sent back to the client)
*/
-typedef int32_t (*qb_ipcs_connection_accept_fn) (qb_ipcs_connection_t *c, uid_t uid,
gid_t gid);
+typedef int32_t (*qb_ipcs_connection_accept_fn) (qb_ipcs_connection_t *c,
+ uid_t uid, gid_t gid);
/**
* This is called after a new connection has been created.
@@ -198,7 +199,8 @@ void qb_ipcs_destroy(qb_ipcs_service_t* s);
* @param s service instance
* @param rl the new rate
*/
-void qb_ipcs_request_rate_limit(qb_ipcs_service_t* s, enum qb_ipcs_rate_limit rl);
+void qb_ipcs_request_rate_limit(qb_ipcs_service_t* s,
+ enum qb_ipcs_rate_limit rl);
/**
* Send a response to a incomming request.
@@ -207,8 +209,13 @@ void qb_ipcs_request_rate_limit(qb_ipcs_service_t* s, enum
qb_ipcs_rate_limit rl
* @param data the message to send
* @param size the size of the message
* @return size sent or -errno for errors
+ *
+ * @note the data must include a qb_ipc_response_header at
+ * the top of the message. The client will read the size field
+ * to determine how much to recv.
*/
-ssize_t qb_ipcs_response_send(qb_ipcs_connection_t *c, const void *data, size_t size);
+ssize_t qb_ipcs_response_send(qb_ipcs_connection_t *c, const void *data,
+ size_t size);
/**
* Send a response to a incomming request.
@@ -217,8 +224,12 @@ ssize_t qb_ipcs_response_send(qb_ipcs_connection_t *c, const void
*data, size_t
* @param iov the iovec struct that points to the message to send
* @param iov_len the number of iovecs.
* @return size sent or -errno for errors
+ *
+ * @note the iov[0] must be a qb_ipc_response_header. The client will
+ * read the size field to determine how much to recv.
*/
-ssize_t qb_ipcs_response_sendv(qb_ipcs_connection_t *c, const struct iovec * iov, size_t
iov_len);
+ssize_t qb_ipcs_response_sendv(qb_ipcs_connection_t *c,
+ const struct iovec * iov, size_t iov_len);
/**
* Send an asyncronous event message to the client.
@@ -227,8 +238,13 @@ ssize_t qb_ipcs_response_sendv(qb_ipcs_connection_t *c, const struct
iovec * iov
* @param data the message to send
* @param size the size of the message
* @return size sent or -errno for errors
+ *
+ * @note the data must include a qb_ipc_response_header at
+ * the top of the message. The client will read the size field
+ * to determine how much to recv.
*/
-ssize_t qb_ipcs_event_send(qb_ipcs_connection_t *c, const void *data, size_t size);
+ssize_t qb_ipcs_event_send(qb_ipcs_connection_t *c, const void *data,
+ size_t size);
/**
* Send an asyncronous event message to the client.
@@ -237,8 +253,12 @@ ssize_t qb_ipcs_event_send(qb_ipcs_connection_t *c, const void *data,
size_t siz
* @param iov the iovec struct that points to the message to send
* @param iov_len the number of iovecs.
* @return size sent or -errno for errors
+ *
+ * @note the iov[0] must be a qb_ipc_response_header. The client will
+ * read the size field to determine how much to recv.
*/
-ssize_t qb_ipcs_event_sendv(qb_ipcs_connection_t *c, const struct iovec * iov, size_t
iov_len);
+ssize_t qb_ipcs_event_sendv(qb_ipcs_connection_t *c, const struct iovec * iov,
+ size_t iov_len);
/**
* Increment the connection's reference counter.
--
1.7.10