Scroll to navigation

qbipcc.h(3) libqb qbipcc.h(3)

NAME

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

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)
 

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
 

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)
 

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)
 

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)
 

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
See also:
qb_ipcc_sendv() qb_ipcc_recv()
 

Author

Generated automatically by Doxygen for libqb from the source code.
Tue Apr 3 2012 Version 0.11.1