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..RS 4 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.RS 4 The function qb_ipcc_sendv_recv() sends an
iovector request and receives a response.Asynchronous requests from the client.RS 4 The function qb_ipcc_sendv() sends
an iovector request. The function qb_ipcc_send() sends an message buffer
request.Asynchronous events from the server.RS 4 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_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.
Version 0.16.0 21 Nov 2013 qbipcc.h(3)
