table of contents
other versions
- jessie 0.11.1-2
- jessie-backports 1.0.1-1~bpo8+1
- stretch 1.0.1-1
- testing 1.0.3-1
- unstable 1.0.3-2
| qbipcc.h(3) | libqb | qbipcc.h(3) |
NAME¶
qbipcc.h - Client IPC API.SYNOPSIS¶
#include <sys/types.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)
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_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_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:
c connection instance
Return values:
connection size in bytes or -error code
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.| Wed Jun 7 2017 | Version 1.0.1 |