qbipcc.h(3) libqb qbipcc.h(3)NAMEqbipcc.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.
Version 0.16.0 Mon May 12 2014 qbipcc.h(3)
