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?

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_tmax_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_tmsg_len,
       int32_tms_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_tmax)
       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_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_tmsg_len,
       int32_tms_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_tmsg_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_tiov_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_tiov_len,
       void *msg_ptr, size_tmsg_len, int32_tms_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_tmax_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.