#include <sys/types.h>
#include <sys/uio.h>
#include <qb/qbipc_common.h>
typedef struct qb_ipcc_connection qb_ipcc_connection_t
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.
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 asynchronous 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.
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.
Get the context (set previously)
Parameters:
c connection instance
Returns:
the context
See also:
qb_ipcc_context_set()
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()
Disconnect an IPC connection.
Parameters:
c connection instance
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.
Set the maximum allowable flowcontrol value.
Note:
the default is 1
Parameters:
c connection instance
max the max allowable flowcontrol value (1 or 2)
Get the file descriptor to poll.
Parameters:
c connection instance
fd (out) file descriptor to poll
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
Is the connection connected?
Parameters:
c connection instance
Return values:
QB_TRUE when connected
QB_FALSE when not connected
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.
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.
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.
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()
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.