NAME

       qbipcc.h - Client IPC API.

SYNOPSIS

       #include <qb/qbconfig.h>
       #include <pthread.h>
       #include <sys/poll.h>
       #include <sys/socket.h>
       #include <qb/qbhdb.h>
       #include <qb/qbipc_common.h>

   Typedefs
       typedef struct qb_ipcc_connection qb_ipcc_connection_t

   Functions
       qb_ipcc_connection_t * qb_ipcc_connect (const char *name, size_t max_msg_size)
           Create a connection to an IPC service.
       int32_t qb_ipcc_verify_dgram_max_msg_size (size_t max_msg_size)
           Test kernel dgram socket buffers to verify the largest size up to the max_msg_size
           value a single msg can be.
       void qb_ipcc_disconnect (qb_ipcc_connection_t *c)
           Disconnect an IPC connection.
       int32_t qb_ipcc_fd_get (qb_ipcc_connection_t *c, int32_t *fd)
           Get the file descriptor to poll.
       int32_t qb_ipcc_fc_enable_max_set (qb_ipcc_connection_t *c, uint32_t max)
           Set the maximum allowable flowcontrol value.
       ssize_t qb_ipcc_send (qb_ipcc_connection_t *c, const void *msg_ptr, size_t msg_len)
           Send a message.
       ssize_t qb_ipcc_sendv (qb_ipcc_connection_t *c, const struct iovec *iov, size_t iov_len)
           Send a message (iovec).
       ssize_t qb_ipcc_recv (qb_ipcc_connection_t *c, void *msg_ptr, size_t msg_len, int32_t
           ms_timeout)
           Receive a response.
       ssize_t qb_ipcc_sendv_recv (qb_ipcc_connection_t *c, const struct iovec *iov, uint32_t
           iov_len, void *msg_ptr, size_t msg_len, int32_t ms_timeout)
           This is a convenience function that simply sends and then recvs.
       ssize_t qb_ipcc_event_recv (qb_ipcc_connection_t *c, void *msg_ptr, size_t msg_len,
           int32_t ms_timeout)
           Receive an event.
       void qb_ipcc_context_set (qb_ipcc_connection_t *c, void *context)
           Associate a 'user' pointer with this connection.
       void * qb_ipcc_context_get (qb_ipcc_connection_t *c)
           Get the context (set previously)
       int32_t qb_ipcc_is_connected (qb_ipcc_connection_t *c)
           Is the connection connected?
       int32_t qb_ipcc_get_buffer_size (qb_ipcc_connection_t *c)
           What is the actual buffer size used after the connection.

Detailed Description

       Client IPC API.

       Lifecycle of an IPC connection.
           An IPC connection is made to the server with qb_ipcc_connect(). This function connects
           to the server and requests channels be created for communication. To disconnect, the
           client either exits or executes the function qb_ipcc_disconnect().

       Synchronous communication
           The function qb_ipcc_sendv_recv() sends an iovector request and receives a response.

       Asynchronous requests from the client
           The function qb_ipcc_sendv() sends an iovector request. The function qb_ipcc_send()
           sends an message buffer request.

       Asynchronous events from the server
           The qb_ipcc_event_recv() function receives an out-of-band asyncronous message. The
           asynchronous messages are queued and can provide very high out-of-band performance. To
           determine when to call qb_ipcc_event_recv() the qb_ipcc_fd_get() call is used to
           obtain a file descriptor used in the poll() or select() system calls.

Typedef Documentation

   typedef struct qb_ipcc_connection qb_ipcc_connection_t

Function Documentation

   qb_ipcc_connection_t* qb_ipcc_connect (const char * name, size_t max_msg_size)
       Create a connection to an IPC service.

       Parameters:
           name name of the service.
           max_msg_size biggest msg size.

       Returns:
           NULL (error: see errno) or a connection object.

       Note:
           It is recommended to do a one time check on the max_msg_size value using
           qb_ipcc_verify_dgram_max_msg_size BEFORE calling the connect function when IPC_SOCKET
           is in use. Some distributions while allow large message buffers to be set on the
           socket, but not actually honor them because of kernel state values. The
           qb_ipcc_verify_dgram_max_msg_size function both sets the socket buffer size and
           verifies it by doing a send/recv.

   void* qb_ipcc_context_get (qb_ipcc_connection_t * c)
       Get the context (set previously)

       Parameters:
           c connection instance

       Returns:
           the context

       See also:
           qb_ipcc_context_set()

   void qb_ipcc_context_set (qb_ipcc_connection_t * c, void * context)
       Associate a 'user' pointer with this connection.

       Parameters:
           context the point to associate with this connection.
           c connection instance

       See also:
           qb_ipcc_context_get()

   void qb_ipcc_disconnect (qb_ipcc_connection_t * c)
       Disconnect an IPC connection.

       Parameters:
           c connection instance

   ssize_t qb_ipcc_event_recv (qb_ipcc_connection_t * c, void * msg_ptr, size_t msg_len, int32_t
       ms_timeout)
       Receive an event.

       Parameters:
           c connection instance
           msg_ptr pointer to a message buffer to receive into
           msg_len the size of the buffer
           ms_timeout time in milli seconds to wait for a message 0 == no wait, negative ==
           block, positive == wait X ms.
           ms_timeout max time to wait for a response

       Returns:
           size of the message or error (-errno)

       Note:
           that msg_ptr will include a qb_ipc_response_header at the top of the message.

   int32_t qb_ipcc_fc_enable_max_set (qb_ipcc_connection_t * c, uint32_t max)
       Set the maximum allowable flowcontrol value.

       Note:
           the default is 1

       Parameters:
           c connection instance
           max the max allowable flowcontrol value (1 or 2)

   int32_t qb_ipcc_fd_get (qb_ipcc_connection_t * c, int32_t * fd)
       Get the file descriptor to poll.

       Parameters:
           c connection instance
           fd (out) file descriptor to poll

   int32_t qb_ipcc_get_buffer_size (qb_ipcc_connection_t * c)
       What is the actual buffer size used after the connection.

       Note:
           The buffer size is guaranteed to be at least the size of the value given in
           qb_ipcc_connect, but it is possible the server will enforce a larger size depending on
           the implementation. If the server side is known to enforce a buffer size, use this
           function after the client connection is established to retrieve the buffer size in
           use. It is important for the client side to know the buffer size in use so the client
           can successfully retrieve large server events.

       Parameters:
           c connection instance

       Return values:
           connection size in bytes or -error code

   int32_t qb_ipcc_is_connected (qb_ipcc_connection_t * c)
       Is the connection connected?

       Parameters:
           c connection instance

       Return values:
           QB_TRUE when connected
           QB_FALSE when not connected

   ssize_t qb_ipcc_recv (qb_ipcc_connection_t * c, void * msg_ptr, size_t msg_len, int32_t
       ms_timeout)
       Receive a response.

       Parameters:
           c connection instance
           msg_ptr pointer to a message buffer to receive into
           msg_len the size of the buffer
           ms_timeout max time to wait for a response

       Returns:
           (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_send (qb_ipcc_connection_t * c, const void * msg_ptr, size_t msg_len)
       Send a message.

       Parameters:
           c connection instance
           msg_ptr pointer to a message to send
           msg_len the size of the message

       Returns:
           (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_sendv (qb_ipcc_connection_t * c, const struct iovec * iov, size_t iov_len)
       Send a message (iovec).

       Parameters:
           c connection instance
           iov pointer to an iovec struct to send
           iov_len the number of iovecs used

       Returns:
           (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_recv (qb_ipcc_connection_t * c, const struct iovec * iov, uint32_t
       iov_len, void * msg_ptr, size_t msg_len, int32_t ms_timeout)
       This is a convenience function that simply sends and then recvs.

       Parameters:
           c connection instance
           iov pointer to an iovec struct to send
           iov_len the number of iovecs used
           msg_ptr pointer to a message buffer to receive into
           msg_len the size of the buffer
           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.

           that msg_ptr will include a qb_ipc_response_header at the top of the message.

       See also:
           qb_ipcc_sendv() qb_ipcc_recv()

   int32_t qb_ipcc_verify_dgram_max_msg_size (size_t max_msg_size)
       Test kernel dgram socket buffers to verify the largest size up to the max_msg_size value a
       single msg can be. Rounds down to the nearest 1k.

       Parameters:
           max_msg_size biggest msg size.

       Returns:
           -1 if max size can not be detected, positive value representing the largest single msg
           up to max_msg_size that can successfully be sent over a unix dgram socket.

Author

       Generated automatically by Doxygen for libqb from the source code.