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?
int32_t qb_ipcc_get_buffer_size (qb_ipcc_connection_t *c)
What is the actual buffer size used after the connection.

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