libqb  1.0.2
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Data Structures | Typedefs | Enumerations | Functions
qbipcs.h File Reference

Server IPC API. More...

#include <sys/types.h>
#include <sys/uio.h>
#include <qb/qbipc_common.h>
#include <qb/qbloop.h>
Include dependency graph for qbipcs.h:

Data Structures

struct  qb_ipcs_stats
 
struct  qb_ipcs_connection_stats
 
struct  qb_ipcs_connection_stats_2
 
struct  qb_ipcs_poll_handlers
 
struct  qb_ipcs_service_handlers
 

Typedefs

typedef struct qb_ipcs_connection qb_ipcs_connection_t
 
typedef struct qb_ipcs_service qb_ipcs_service_t
 
typedef int32_t(* qb_ipcs_dispatch_fn_t )(int32_t fd, int32_t revents, void *data)
 
typedef int32_t(* qb_ipcs_dispatch_add_fn )(enum qb_loop_priority p, int32_t fd, int32_t events, void *data, qb_ipcs_dispatch_fn_t fn)
 
typedef int32_t(* qb_ipcs_dispatch_mod_fn )(enum qb_loop_priority p, int32_t fd, int32_t events, void *data, qb_ipcs_dispatch_fn_t fn)
 
typedef int32_t(* qb_ipcs_dispatch_del_fn )(int32_t fd)
 
typedef int32_t(* qb_ipcs_job_add_fn )(enum qb_loop_priority p, void *data, qb_loop_job_dispatch_fn dispatch_fn)
 
typedef int32_t(* qb_ipcs_connection_accept_fn )(qb_ipcs_connection_t *c, uid_t uid, gid_t gid)
 This callback is to check whether you want to accept a new connection. More...
 
typedef void(* qb_ipcs_connection_created_fn )(qb_ipcs_connection_t *c)
 This is called after a new connection has been created. More...
 
typedef int32_t(* qb_ipcs_connection_closed_fn )(qb_ipcs_connection_t *c)
 This is called after a connection has been disconnected. More...
 
typedef void(* qb_ipcs_connection_destroyed_fn )(qb_ipcs_connection_t *c)
 This is called just before a connection is freed. More...
 
typedef int32_t(* qb_ipcs_msg_process_fn )(qb_ipcs_connection_t *c, void *data, size_t size)
 This is the message processing calback. More...
 

Enumerations

enum  qb_ipcs_rate_limit {
  QB_IPCS_RATE_FAST, QB_IPCS_RATE_NORMAL, QB_IPCS_RATE_SLOW, QB_IPCS_RATE_OFF,
  QB_IPCS_RATE_OFF_2
}
 

Functions

qb_ipcs_service_tqb_ipcs_create (const char *name, int32_t service_id, enum qb_ipc_type type, struct qb_ipcs_service_handlers *handlers)
 Create a new IPC server. More...
 
void qb_ipcs_ref (qb_ipcs_service_t *s)
 Increase the reference counter on the service object. More...
 
void qb_ipcs_unref (qb_ipcs_service_t *s)
 Decrease the reference counter on the service object. More...
 
void qb_ipcs_poll_handlers_set (qb_ipcs_service_t *s, struct qb_ipcs_poll_handlers *handlers)
 Set your poll callbacks. More...
 
void qb_ipcs_service_context_set (qb_ipcs_service_t *s, void *context)
 Associate a "user" pointer with this service. More...
 
void * qb_ipcs_service_context_get (qb_ipcs_service_t *s)
 Get the context (set previously) More...
 
int32_t qb_ipcs_run (qb_ipcs_service_t *s)
 run the new IPC server. More...
 
void qb_ipcs_destroy (qb_ipcs_service_t *s)
 Destroy the IPC server. More...
 
void qb_ipcs_request_rate_limit (qb_ipcs_service_t *s, enum qb_ipcs_rate_limit rl)
 Limit the incoming request rate. More...
 
ssize_t qb_ipcs_response_send (qb_ipcs_connection_t *c, const void *data, size_t size)
 Send a response to a incoming request. More...
 
ssize_t qb_ipcs_response_sendv (qb_ipcs_connection_t *c, const struct iovec *iov, size_t iov_len)
 Send a response to a incoming request. More...
 
ssize_t qb_ipcs_event_send (qb_ipcs_connection_t *c, const void *data, size_t size)
 Send an asynchronous event message to the client. More...
 
ssize_t qb_ipcs_event_sendv (qb_ipcs_connection_t *c, const struct iovec *iov, size_t iov_len)
 Send an asynchronous event message to the client. More...
 
void qb_ipcs_connection_ref (qb_ipcs_connection_t *c)
 Increment the connection's reference counter. More...
 
void qb_ipcs_connection_unref (qb_ipcs_connection_t *c)
 Decrement the connection's reference counter. More...
 
void qb_ipcs_disconnect (qb_ipcs_connection_t *c)
 Disconnect from this client. More...
 
int32_t qb_ipcs_service_id_get (qb_ipcs_connection_t *c)
 Get the service id related to this connection's service. More...
 
void qb_ipcs_context_set (qb_ipcs_connection_t *c, void *context)
 Associate a "user" pointer with this connection. More...
 
void * qb_ipcs_context_get (qb_ipcs_connection_t *c)
 Get the context (set previously) More...
 
void * qb_ipcs_connection_service_context_get (qb_ipcs_connection_t *c)
 Get the context previously set on the service backing this connection. More...
 
int32_t qb_ipcs_connection_stats_get (qb_ipcs_connection_t *c, struct qb_ipcs_connection_stats *stats, int32_t clear_after_read)
 Get the connection statistics. More...
 
struct qb_ipcs_connection_stats_2qb_ipcs_connection_stats_get_2 (qb_ipcs_connection_t *c, int32_t clear_after_read)
 Get (and allocate) the connection statistics. More...
 
int32_t qb_ipcs_stats_get (qb_ipcs_service_t *pt, struct qb_ipcs_stats *stats, int32_t clear_after_read)
 Get the service statistics. More...
 
qb_ipcs_connection_tqb_ipcs_connection_first_get (qb_ipcs_service_t *pt)
 Get the first connection. More...
 
qb_ipcs_connection_tqb_ipcs_connection_next_get (qb_ipcs_service_t *pt, qb_ipcs_connection_t *current)
 Get the next connection. More...
 
void qb_ipcs_connection_auth_set (qb_ipcs_connection_t *conn, uid_t uid, gid_t gid, mode_t mode)
 Set the permissions on and shared memory files so that both processes can read and write to them. More...
 
int32_t qb_ipcs_connection_get_buffer_size (qb_ipcs_connection_t *conn)
 Retrieve the connection ipc buffer size. More...
 
void qb_ipcs_enforce_buffer_size (qb_ipcs_service_t *s, uint32_t max_buf_size)
 Enforce the max buffer size clients must use from the server side. More...
 

Detailed Description

Server IPC API.

Typedef Documentation

typedef int32_t(* qb_ipcs_connection_accept_fn)(qb_ipcs_connection_t *c, uid_t uid, gid_t gid)

This callback is to check whether you want to accept a new connection.

The type of checks you should do are authentication, service availability or process resource constraints.

Returns
0 to accept or -errno to indicate a failure (sent back to the client)
Note
If connection state data is allocated as a result of this callback being invoked, that data must be freed in the destroy callback. Just because the accept callback returns 0, that does not guarantee the create and closed callback functions will follow.
you can call qb_ipcs_connection_auth_set() within this function.
typedef int32_t(* qb_ipcs_connection_closed_fn)(qb_ipcs_connection_t *c)

This is called after a connection has been disconnected.

Note
This callback will only be invoked if the connection is successfully created.
if you return anything but 0 this function will be repeativily called (until 0 is returned).
typedef void(* qb_ipcs_connection_created_fn)(qb_ipcs_connection_t *c)

This is called after a new connection has been created.

Note
A client connection is not considered connected until this callback is invoked.
typedef void(* qb_ipcs_connection_destroyed_fn)(qb_ipcs_connection_t *c)

This is called just before a connection is freed.

typedef struct qb_ipcs_connection qb_ipcs_connection_t
typedef int32_t(* qb_ipcs_dispatch_add_fn)(enum qb_loop_priority p, int32_t fd, int32_t events, void *data, qb_ipcs_dispatch_fn_t fn)
typedef int32_t(* qb_ipcs_dispatch_del_fn)(int32_t fd)
typedef int32_t(* qb_ipcs_dispatch_fn_t)(int32_t fd, int32_t revents, void *data)
Examples:
ipcserver.c.
typedef int32_t(* qb_ipcs_dispatch_mod_fn)(enum qb_loop_priority p, int32_t fd, int32_t events, void *data, qb_ipcs_dispatch_fn_t fn)
typedef int32_t(* qb_ipcs_job_add_fn)(enum qb_loop_priority p, void *data, qb_loop_job_dispatch_fn dispatch_fn)
typedef int32_t(* qb_ipcs_msg_process_fn)(qb_ipcs_connection_t *c, void *data, size_t size)

This is the message processing calback.

It is called with the message data.

typedef struct qb_ipcs_service qb_ipcs_service_t

Enumeration Type Documentation

Enumerator
QB_IPCS_RATE_FAST 
QB_IPCS_RATE_NORMAL 
QB_IPCS_RATE_SLOW 
QB_IPCS_RATE_OFF 
QB_IPCS_RATE_OFF_2 

Function Documentation

void qb_ipcs_connection_auth_set ( qb_ipcs_connection_t conn,
uid_t  uid,
gid_t  gid,
mode_t  mode 
)

Set the permissions on and shared memory files so that both processes can read and write to them.

Parameters
connconnection instance
uidthe user id to set.
gidthe group id to set.
modethe mode to set.
See Also
chmod() chown()
Note
this must be called within the qb_ipcs_connection_accept_fn() callback.
qb_ipcs_connection_t* qb_ipcs_connection_first_get ( qb_ipcs_service_t pt)

Get the first connection.

Note
call qb_ipcs_connection_unref() after using the connection.
Parameters
ptservice instance
Returns
first connection
int32_t qb_ipcs_connection_get_buffer_size ( qb_ipcs_connection_t conn)

Retrieve the connection ipc buffer size.

This reflects the largest size msg that can be sent or received.

Parameters
connconnection instance
Returns
msg size in bytes, negative value on error.
qb_ipcs_connection_t* qb_ipcs_connection_next_get ( qb_ipcs_service_t pt,
qb_ipcs_connection_t current 
)

Get the next connection.

Note
call qb_ipcs_connection_unref() after using the connection.
Parameters
ptservice instance
currentcurrent connection
Returns
next connection
void qb_ipcs_connection_ref ( qb_ipcs_connection_t c)

Increment the connection's reference counter.

Parameters
cconnection instance
void* qb_ipcs_connection_service_context_get ( qb_ipcs_connection_t c)

Get the context previously set on the service backing this connection.

Parameters
cconnection instance
Returns
the context
See Also
qb_ipcs_service_context_set
int32_t qb_ipcs_connection_stats_get ( qb_ipcs_connection_t c,
struct qb_ipcs_connection_stats stats,
int32_t  clear_after_read 
)

Get the connection statistics.

Deprecated:
from v0.13.0 onwards, use qb_ipcs_connection_stats_get_2
Parameters
stats(out) the statistics structure
clear_after_readclear stats after copying them into stats
cconnection instance
Returns
0 == ok; -errno to indicate a failure
Examples:
ipcserver.c.
struct qb_ipcs_connection_stats_2* qb_ipcs_connection_stats_get_2 ( qb_ipcs_connection_t c,
int32_t  clear_after_read 
)

Get (and allocate) the connection statistics.

Parameters
clear_after_readclear stats after copying them into stats
cconnection instance
Return values
NULLif no memory or invalid connection
allocatedstatistics structure (user must free it).
void qb_ipcs_connection_unref ( qb_ipcs_connection_t c)

Decrement the connection's reference counter.

Parameters
cconnection instance
void* qb_ipcs_context_get ( qb_ipcs_connection_t c)

Get the context (set previously)

Parameters
cconnection instance
Returns
the context
See Also
qb_ipcs_context_set()
void qb_ipcs_context_set ( qb_ipcs_connection_t c,
void *  context 
)

Associate a "user" pointer with this connection.

Parameters
contextthe point to associate with this connection.
cconnection instance
See Also
qb_ipcs_context_get()
qb_ipcs_service_t* qb_ipcs_create ( const char *  name,
int32_t  service_id,
enum qb_ipc_type  type,
struct qb_ipcs_service_handlers handlers 
)

Create a new IPC server.

Parameters
namefor clients to connect to.
service_idan integer to associate with the service
typetransport type.
handlerscallbacks.
Returns
the new service instance.
Examples:
ipcserver.c.
void qb_ipcs_destroy ( qb_ipcs_service_t s)

Destroy the IPC server.

Parameters
sservice instance to destroy
Examples:
ipcserver.c.
void qb_ipcs_disconnect ( qb_ipcs_connection_t c)

Disconnect from this client.

Parameters
cconnection instance
void qb_ipcs_enforce_buffer_size ( qb_ipcs_service_t s,
uint32_t  max_buf_size 
)

Enforce the max buffer size clients must use from the server side.

Note
Setting this will force client connections to use at least max_buf_size bytes as their buffer size. If this value is not set on the server, the clients enforce their own buffer sizes.
Parameters
sipc server instance
max_buf_sizerepresented in bytes
Examples:
ipcserver.c.
ssize_t qb_ipcs_event_send ( qb_ipcs_connection_t c,
const void *  data,
size_t  size 
)

Send an asynchronous event message to the client.

Parameters
cconnection instance
datathe message to send
sizethe size of the message
Returns
size sent or -errno for errors
Note
the data must include a qb_ipc_response_header at the top of the message. The client will read the size field to determine how much to recv.
When send returns -EMSGSIZE, this means the msg is too large and will never succeed. To determine the max msg size a client can be sent, use qb_ipcs_connection_get_buffer_size()
ssize_t qb_ipcs_event_sendv ( qb_ipcs_connection_t c,
const struct iovec *  iov,
size_t  iov_len 
)

Send an asynchronous event message to the client.

Parameters
cconnection instance
iovthe iovec struct that points to the message to send
iov_lenthe number of iovecs.
Returns
size sent or -errno for errors
Note
the iov[0] must be a qb_ipc_response_header. The client will read the size field to determine how much to recv.
When send returns -EMSGSIZE, this means the msg is too large and will never succeed. To determine the max msg size a client can be sent, use qb_ipcs_connection_get_buffer_size()
Examples:
ipcserver.c.
void qb_ipcs_poll_handlers_set ( qb_ipcs_service_t s,
struct qb_ipcs_poll_handlers handlers 
)

Set your poll callbacks.

Parameters
sservice instance
handlersthe handlers that you want ipcs to use.
Examples:
ipcserver.c.
void qb_ipcs_ref ( qb_ipcs_service_t s)

Increase the reference counter on the service object.

Parameters
sservice instance
void qb_ipcs_request_rate_limit ( qb_ipcs_service_t s,
enum qb_ipcs_rate_limit  rl 
)

Limit the incoming request rate.

Parameters
sservice instance
rlthe new rate
ssize_t qb_ipcs_response_send ( qb_ipcs_connection_t c,
const void *  data,
size_t  size 
)

Send a response to a incoming request.

Parameters
cconnection instance
datathe message to send
sizethe size of the message
Returns
size sent or -errno for errors
Note
the data must include a qb_ipc_response_header at the top of the message. The client will read the size field to determine how much to recv.
ssize_t qb_ipcs_response_sendv ( qb_ipcs_connection_t c,
const struct iovec *  iov,
size_t  iov_len 
)

Send a response to a incoming request.

Parameters
cconnection instance
iovthe iovec struct that points to the message to send
iov_lenthe number of iovecs.
Returns
size sent or -errno for errors
Note
the iov[0] must be a qb_ipc_response_header. The client will read the size field to determine how much to recv.
When send returns -EMSGSIZE, this means the msg is too large and will never succeed. To determine the max msg size a client can be sent, use qb_ipcs_connection_get_buffer_size()
Examples:
ipcserver.c.
int32_t qb_ipcs_run ( qb_ipcs_service_t s)

run the new IPC server.

Parameters
sservice instance
Returns
0 == ok; -errno to indicate a failure. Service is destroyed on failure.
Examples:
ipcserver.c.
void* qb_ipcs_service_context_get ( qb_ipcs_service_t s)

Get the context (set previously)

Parameters
sservice instance
Returns
the context
See Also
qb_ipcs_service_context_set()
void qb_ipcs_service_context_set ( qb_ipcs_service_t s,
void *  context 
)

Associate a "user" pointer with this service.

Parameters
sservice instance
contextthe pointer to associate with this service.
See Also
qb_ipcs_service_context_get()
int32_t qb_ipcs_service_id_get ( qb_ipcs_connection_t c)

Get the service id related to this connection's service.

(as passed into qb_ipcs_create()

Returns
service id.
int32_t qb_ipcs_stats_get ( qb_ipcs_service_t pt,
struct qb_ipcs_stats stats,
int32_t  clear_after_read 
)

Get the service statistics.

Parameters
stats(out) the statistics structure
clear_after_readclear stats after copying them into stats
ptservice instance
Returns
0 == ok; -errno to indicate a failure
Examples:
ipcserver.c.
void qb_ipcs_unref ( qb_ipcs_service_t s)

Decrease the reference counter on the service object.

Parameters
sservice instance