libqb  1.0.2
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Typedefs | Functions
qbipcc.h File Reference

Client IPC API. More...

#include <sys/types.h>
#include <sys/uio.h>
#include <qb/qbipc_common.h>
Include dependency graph for qbipcc.h:

Typedefs

typedef struct qb_ipcc_connection qb_ipcc_connection_t
 

Functions

qb_ipcc_connection_tqb_ipcc_connect (const char *name, size_t max_msg_size)
 Create a connection to an IPC service. More...
 
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. More...
 
void qb_ipcc_disconnect (qb_ipcc_connection_t *c)
 Disconnect an IPC connection. More...
 
int32_t qb_ipcc_fd_get (qb_ipcc_connection_t *c, int32_t *fd)
 Get the file descriptor to poll. More...
 
int32_t qb_ipcc_fc_enable_max_set (qb_ipcc_connection_t *c, uint32_t max)
 Set the maximum allowable flowcontrol value. More...
 
ssize_t qb_ipcc_send (qb_ipcc_connection_t *c, const void *msg_ptr, size_t msg_len)
 Send a message. More...
 
ssize_t qb_ipcc_sendv (qb_ipcc_connection_t *c, const struct iovec *iov, size_t iov_len)
 Send a message (iovec). More...
 
ssize_t qb_ipcc_recv (qb_ipcc_connection_t *c, void *msg_ptr, size_t msg_len, int32_t ms_timeout)
 Receive a response. More...
 
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. More...
 
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. More...
 
void qb_ipcc_context_set (qb_ipcc_connection_t *c, void *context)
 Associate a "user" pointer with this connection. More...
 
void * qb_ipcc_context_get (qb_ipcc_connection_t *c)
 Get the context (set previously) More...
 
int32_t qb_ipcc_is_connected (qb_ipcc_connection_t *c)
 Is the connection connected? More...
 
int32_t qb_ipcc_get_buffer_size (qb_ipcc_connection_t *c)
 What is the actual buffer size used after the connection. More...
 

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 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.

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
namename of the service.
max_msg_sizebiggest 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.
Examples:
ipcclient.c.
void* qb_ipcc_context_get ( qb_ipcc_connection_t c)

Get the context (set previously)

Parameters
cconnection 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
contextthe point to associate with this connection.
cconnection instance
See Also
qb_ipcc_context_get()
void qb_ipcc_disconnect ( qb_ipcc_connection_t c)

Disconnect an IPC connection.

Parameters
cconnection instance
Examples:
ipcclient.c.
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
cconnection instance
msg_ptrpointer to a message buffer to receive into
msg_lenthe size of the buffer
ms_timeouttime in milli seconds to wait for a message 0 == no wait, negative == block, positive == wait X ms.
ms_timeoutmax 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.
Examples:
ipcclient.c.
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
cconnection instance
maxthe 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
cconnection 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
cconnection instance
Return values
connectionsize in bytes or -error code
Examples:
ipcclient.c.
int32_t qb_ipcc_is_connected ( qb_ipcc_connection_t c)

Is the connection connected?

Parameters
cconnection instance
Return values
QB_TRUEwhen connected
QB_FALSEwhen 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
cconnection instance
msg_ptrpointer to a message buffer to receive into
msg_lenthe size of the buffer
ms_timeoutmax 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.
Examples:
ipcclient.c.
ssize_t qb_ipcc_send ( qb_ipcc_connection_t c,
const void *  msg_ptr,
size_t  msg_len 
)

Send a message.

Parameters
cconnection instance
msg_ptrpointer to a message to send
msg_lenthe 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.
Examples:
ipcclient.c.
ssize_t qb_ipcc_sendv ( qb_ipcc_connection_t c,
const struct iovec *  iov,
size_t  iov_len 
)

Send a message (iovec).

Parameters
cconnection instance
iovpointer to an iovec struct to send
iov_lenthe 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.
Examples:
ipcclient.c.
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
cconnection instance
iovpointer to an iovec struct to send
iov_lenthe number of iovecs used
msg_ptrpointer to a message buffer to receive into
msg_lenthe size of the buffer
ms_timeoutmax 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_sizebiggest 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.