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

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 \fBqb_ipcc_connection_t\fP

Function Documentation

\fBqb_ipcc_connection_t\fP* \fBqb_ipcc_connect\fP (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.

void* \fBqb_ipcc_context_get\fP (\fBqb_ipcc_connection_t\fP *c)

Get the context (set previously) Parameters:

c connection instance

Returns:

the context

See also:

qb_ipcc_context_set()

void \fBqb_ipcc_context_set\fP (\fBqb_ipcc_connection_t\fP *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 \fBqb_ipcc_disconnect\fP (\fBqb_ipcc_connection_t\fP *c)

Disconnect an IPC connection. Parameters:

c connection instance

ssize_t \fBqb_ipcc_event_recv\fP (\fBqb_ipcc_connection_t\fP *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)

int32_t \fBqb_ipcc_fc_enable_max_set\fP (\fBqb_ipcc_connection_t\fP *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 \fBqb_ipcc_fd_get\fP (\fBqb_ipcc_connection_t\fP *c, int32_t *fd)

Get the file descriptor to poll. Parameters:

c connection instance

fd (out) file descriptor to poll

ssize_t \fBqb_ipcc_recv\fP (\fBqb_ipcc_connection_t\fP *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)

ssize_t \fBqb_ipcc_send\fP (\fBqb_ipcc_connection_t\fP *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)

ssize_t \fBqb_ipcc_sendv\fP (\fBqb_ipcc_connection_t\fP *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)

ssize_t \fBqb_ipcc_sendv_recv\fP (\fBqb_ipcc_connection_t\fP *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

See also:

qb_ipcc_sendv() qb_ipcc_recv()

Author

Generated automatically by Doxygen for libqb from the source code.