.TH "qbipcc.h" 3 "Thu Dec 21 2017" "Version 1.0.3" "libqb" \" -*- nroff -*-
.ad l
.nh
.SH NAME
qbipcc.h \- 
.PP
Client IPC API\&.  

.SH SYNOPSIS
.br
.PP
\fC#include <sys/types\&.h>\fP
.br
\fC#include <sys/uio\&.h>\fP
.br
\fC#include <qb/qbipc_common\&.h>\fP
.br

.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct qb_ipcc_connection \fBqb_ipcc_connection_t\fP"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBqb_ipcc_connection_t\fP * \fBqb_ipcc_connect\fP (const char *name, size_t max_msg_size)"
.br
.RI "\fICreate a connection to an IPC service\&. \fP"
.ti -1c
.RI "int32_t \fBqb_ipcc_verify_dgram_max_msg_size\fP (size_t max_msg_size)"
.br
.RI "\fITest kernel dgram socket buffers to verify the largest size up to the max_msg_size value a single msg can be\&. \fP"
.ti -1c
.RI "void \fBqb_ipcc_disconnect\fP (\fBqb_ipcc_connection_t\fP *c)"
.br
.RI "\fIDisconnect an IPC connection\&. \fP"
.ti -1c
.RI "int32_t \fBqb_ipcc_fd_get\fP (\fBqb_ipcc_connection_t\fP *c, int32_t *fd)"
.br
.RI "\fIGet the file descriptor to poll\&. \fP"
.ti -1c
.RI "int32_t \fBqb_ipcc_fc_enable_max_set\fP (\fBqb_ipcc_connection_t\fP *c, uint32_t max)"
.br
.RI "\fISet the maximum allowable flowcontrol value\&. \fP"
.ti -1c
.RI "ssize_t \fBqb_ipcc_send\fP (\fBqb_ipcc_connection_t\fP *c, const void *msg_ptr, size_t msg_len)"
.br
.RI "\fISend a message\&. \fP"
.ti -1c
.RI "ssize_t \fBqb_ipcc_sendv\fP (\fBqb_ipcc_connection_t\fP *c, const struct iovec *iov, size_t iov_len)"
.br
.RI "\fISend a message (iovec)\&. \fP"
.ti -1c
.RI "ssize_t \fBqb_ipcc_recv\fP (\fBqb_ipcc_connection_t\fP *c, void *msg_ptr, size_t msg_len, int32_t ms_timeout)"
.br
.RI "\fIReceive a response\&. \fP"
.ti -1c
.RI "ssize_t \fBqb_ipcc_sendv_recv\fP (\fBqb_ipcc_connection_t\fP *c, const struct iovec *iov, uint32_t iov_len, void *msg_ptr, size_t msg_len, int32_t ms_timeout)"
.br
.RI "\fIThis is a convenience function that simply sends and then recvs\&. \fP"
.ti -1c
.RI "ssize_t \fBqb_ipcc_event_recv\fP (\fBqb_ipcc_connection_t\fP *c, void *msg_ptr, size_t msg_len, int32_t ms_timeout)"
.br
.RI "\fIReceive an event\&. \fP"
.ti -1c
.RI "void \fBqb_ipcc_context_set\fP (\fBqb_ipcc_connection_t\fP *c, void *context)"
.br
.RI "\fIAssociate a 'user' pointer with this connection\&. \fP"
.ti -1c
.RI "void * \fBqb_ipcc_context_get\fP (\fBqb_ipcc_connection_t\fP *c)"
.br
.RI "\fIGet the context (set previously) \fP"
.ti -1c
.RI "int32_t \fBqb_ipcc_is_connected\fP (\fBqb_ipcc_connection_t\fP *c)"
.br
.RI "\fIIs the connection connected? \fP"
.ti -1c
.RI "int32_t \fBqb_ipcc_get_buffer_size\fP (\fBqb_ipcc_connection_t\fP *c)"
.br
.RI "\fIWhat is the actual buffer size used after the connection\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 
Client IPC API\&. 


.PP
\fBLifecycle of an IPC connection\&.\fP
.RS 4
An IPC connection is made to the server with \fBqb_ipcc_connect()\fP\&. This function connects to the server and requests channels be created for communication\&. To disconnect, the client either exits or executes the function \fBqb_ipcc_disconnect()\fP\&.
.RE
.PP
\fBSynchronous communication\fP
.RS 4
The function \fBqb_ipcc_sendv_recv()\fP sends an iovector request and receives a response\&.
.RE
.PP
\fBAsynchronous requests from the client\fP
.RS 4
The function \fBqb_ipcc_sendv()\fP sends an iovector request\&. The function \fBqb_ipcc_send()\fP sends an message buffer request\&.
.RE
.PP
\fBAsynchronous events from the server\fP
.RS 4
The \fBqb_ipcc_event_recv()\fP 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 \fBqb_ipcc_event_recv()\fP the \fBqb_ipcc_fd_get()\fP call is used to obtain a file descriptor used in the poll() or select() system calls\&. 
.RE
.PP

.SH "Typedef Documentation"
.PP 
.SS "typedef struct qb_ipcc_connection \fBqb_ipcc_connection_t\fP"

.SH "Function Documentation"
.PP 
.SS "\fBqb_ipcc_connection_t\fP* qb_ipcc_connect (const char *name, size_tmax_msg_size)"

.PP
Create a connection to an IPC service\&. 
.PP
\fBParameters:\fP
.RS 4
\fIname\fP name of the service\&. 
.br
\fImax_msg_size\fP biggest msg size\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
NULL (error: see errno) or a connection object\&.
.RE
.PP
\fBNote:\fP
.RS 4
It is recommended to do a one time check on the max_msg_size value using qb_ipcc_verify_dgram_max_msg_size \fIBEFORE\fP 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\&. 
.RE
.PP

.SS "void* qb_ipcc_context_get (\fBqb_ipcc_connection_t\fP *c)"

.PP
Get the context (set previously) 
.PP
\fBParameters:\fP
.RS 4
\fIc\fP connection instance 
.RE
.PP
\fBReturns:\fP
.RS 4
the context 
.RE
.PP
\fBSee Also:\fP
.RS 4
\fBqb_ipcc_context_set()\fP 
.RE
.PP

.SS "void qb_ipcc_context_set (\fBqb_ipcc_connection_t\fP *c, void *context)"

.PP
Associate a 'user' pointer with this connection\&. 
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP the point to associate with this connection\&. 
.br
\fIc\fP connection instance 
.RE
.PP
\fBSee Also:\fP
.RS 4
\fBqb_ipcc_context_get()\fP 
.RE
.PP

.SS "void qb_ipcc_disconnect (\fBqb_ipcc_connection_t\fP *c)"

.PP
Disconnect an IPC connection\&. 
.PP
\fBParameters:\fP
.RS 4
\fIc\fP connection instance 
.RE
.PP

.SS "ssize_t qb_ipcc_event_recv (\fBqb_ipcc_connection_t\fP *c, void *msg_ptr, size_tmsg_len, int32_tms_timeout)"

.PP
Receive an event\&. 
.PP
\fBParameters:\fP
.RS 4
\fIc\fP connection instance 
.br
\fImsg_ptr\fP pointer to a message buffer to receive into 
.br
\fImsg_len\fP the size of the buffer 
.br
\fIms_timeout\fP time in milli seconds to wait for a message 0 == no wait, negative == block, positive == wait X ms\&. 
.br
\fIms_timeout\fP max time to wait for a response 
.RE
.PP
\fBReturns:\fP
.RS 4
size of the message or error (-errno)
.RE
.PP
\fBNote:\fP
.RS 4
that msg_ptr will include a \fBqb_ipc_response_header\fP at the top of the message\&. 
.RE
.PP

.SS "int32_t qb_ipcc_fc_enable_max_set (\fBqb_ipcc_connection_t\fP *c, uint32_tmax)"

.PP
Set the maximum allowable flowcontrol value\&. 
.PP
\fBNote:\fP
.RS 4
the default is 1
.RE
.PP
\fBParameters:\fP
.RS 4
\fIc\fP connection instance 
.br
\fImax\fP the max allowable flowcontrol value (1 or 2) 
.RE
.PP

.SS "int32_t qb_ipcc_fd_get (\fBqb_ipcc_connection_t\fP *c, int32_t *fd)"

.PP
Get the file descriptor to poll\&. 
.PP
\fBParameters:\fP
.RS 4
\fIc\fP connection instance 
.br
\fIfd\fP (out) file descriptor to poll 
.RE
.PP

.SS "int32_t qb_ipcc_get_buffer_size (\fBqb_ipcc_connection_t\fP *c)"

.PP
What is the actual buffer size used after the connection\&. 
.PP
\fBNote:\fP
.RS 4
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\&.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIc\fP connection instance 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIconnection\fP size in bytes or -error code 
.RE
.PP

.SS "int32_t qb_ipcc_is_connected (\fBqb_ipcc_connection_t\fP *c)"

.PP
Is the connection connected? 
.PP
\fBParameters:\fP
.RS 4
\fIc\fP connection instance 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fIQB_TRUE\fP when connected 
.br
\fIQB_FALSE\fP when not connected 
.RE
.PP

.SS "ssize_t qb_ipcc_recv (\fBqb_ipcc_connection_t\fP *c, void *msg_ptr, size_tmsg_len, int32_tms_timeout)"

.PP
Receive a response\&. 
.PP
\fBParameters:\fP
.RS 4
\fIc\fP connection instance 
.br
\fImsg_ptr\fP pointer to a message buffer to receive into 
.br
\fImsg_len\fP the size of the buffer 
.br
\fIms_timeout\fP max time to wait for a response 
.RE
.PP
\fBReturns:\fP
.RS 4
(size recv'ed, -errno == error)
.RE
.PP
\fBNote:\fP
.RS 4
that msg_ptr will include a \fBqb_ipc_response_header\fP at the top of the message\&. 
.RE
.PP

.SS "ssize_t qb_ipcc_send (\fBqb_ipcc_connection_t\fP *c, const void *msg_ptr, size_tmsg_len)"

.PP
Send a message\&. 
.PP
\fBParameters:\fP
.RS 4
\fIc\fP connection instance 
.br
\fImsg_ptr\fP pointer to a message to send 
.br
\fImsg_len\fP the size of the message 
.RE
.PP
\fBReturns:\fP
.RS 4
(size sent, -errno == error)
.RE
.PP
\fBNote:\fP
.RS 4
the msg_ptr must include a \fBqb_ipc_request_header\fP at the top of the message\&. The server will read the size field to determine how much to recv\&. 
.RE
.PP

.SS "ssize_t qb_ipcc_sendv (\fBqb_ipcc_connection_t\fP *c, const struct iovec *iov, size_tiov_len)"

.PP
Send a message (iovec)\&. 
.PP
\fBParameters:\fP
.RS 4
\fIc\fP connection instance 
.br
\fIiov\fP pointer to an iovec struct to send 
.br
\fIiov_len\fP the number of iovecs used 
.RE
.PP
\fBReturns:\fP
.RS 4
(size sent, -errno == error)
.RE
.PP
\fBNote:\fP
.RS 4
the iov[0] must be a \fBqb_ipc_request_header\fP\&. The server will read the size field to determine how much to recv\&. 
.RE
.PP

.SS "ssize_t qb_ipcc_sendv_recv (\fBqb_ipcc_connection_t\fP *c, const struct iovec *iov, uint32_tiov_len, void *msg_ptr, size_tmsg_len, int32_tms_timeout)"

.PP
This is a convenience function that simply sends and then recvs\&. 
.PP
\fBParameters:\fP
.RS 4
\fIc\fP connection instance 
.br
\fIiov\fP pointer to an iovec struct to send 
.br
\fIiov_len\fP the number of iovecs used 
.br
\fImsg_ptr\fP pointer to a message buffer to receive into 
.br
\fImsg_len\fP the size of the buffer 
.br
\fIms_timeout\fP max time to wait for a response
.RE
.PP
\fBNote:\fP
.RS 4
the iov[0] must include a \fBqb_ipc_request_header\fP at the top of the message\&. The server will read the size field to determine how much to recv\&. 
.PP
that msg_ptr will include a \fBqb_ipc_response_header\fP at the top of the message\&.
.RE
.PP
\fBSee Also:\fP
.RS 4
\fBqb_ipcc_sendv()\fP \fBqb_ipcc_recv()\fP 
.RE
.PP

.SS "int32_t qb_ipcc_verify_dgram_max_msg_size (size_tmax_msg_size)"

.PP
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\&.
.PP
\fBParameters:\fP
.RS 4
\fImax_msg_size\fP biggest msg size\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
-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\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libqb from the source code\&.