qbipcs.h(3) libqb qbipcs.h(3)NAMEqbipcs.h-
Server IPC API.
SYNOPSIS
#include <stdlib.h>
#include <sys/uio.h>
#include <qb/qbipc_common.h>
#include <qb/qbhdb.h>
#include <qb/qbloop.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 wether you want to accept a new
connection.
typedef void(* qb_ipcs_connection_created_fn )(qb_ipcs_connection_t *c)
This is called after a new connection has been created.
typedef int32_t(* qb_ipcs_connection_closed_fn )(qb_ipcs_connection_t
*c)
This is called after a connection has been disconnected.
typedef void(* qb_ipcs_connection_destroyed_fn )(qb_ipcs_connection_t
*c)
This is called just before a connection is freed.
typedef int32_t(* qb_ipcs_msg_process_fn )(qb_ipcs_connection_t *c,
void *data, size_t size)
This is the message processing calback.
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_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.
void qb_ipcs_ref (qb_ipcs_service_t *s)
Increase the reference counter on the service object.
void qb_ipcs_unref (qb_ipcs_service_t *s)
Decrease the reference counter on the service object.
void qb_ipcs_poll_handlers_set (qb_ipcs_service_t *s, struct
qb_ipcs_poll_handlers *handlers)
Set your poll callbacks.
void qb_ipcs_service_context_set (qb_ipcs_service_t *s, void *context)
Associate a 'user' pointer with this service.
void * qb_ipcs_service_context_get (qb_ipcs_service_t *s)
Get the context (set previously).
int32_t qb_ipcs_run (qb_ipcs_service_t *s)
run the new IPC server.
void qb_ipcs_destroy (qb_ipcs_service_t *s)
Destroy the IPC server.
void qb_ipcs_request_rate_limit (qb_ipcs_service_t *s, enum
qb_ipcs_rate_limit rl)
Limit the incomming request rate.
ssize_t qb_ipcs_response_send (qb_ipcs_connection_t *c, const void
*data, size_t size)
Send a response to a incomming request.
ssize_t qb_ipcs_response_sendv (qb_ipcs_connection_t *c, const struct
iovec *iov, size_t iov_len)
Send a response to a incomming request.
ssize_t qb_ipcs_event_send (qb_ipcs_connection_t *c, const void *data,
size_t size)
Send an asyncronous event message to the client.
ssize_t qb_ipcs_event_sendv (qb_ipcs_connection_t *c, const struct
iovec *iov, size_t iov_len)
Send an asyncronous event message to the client.
void qb_ipcs_connection_ref (qb_ipcs_connection_t *c)
Increment the connection's reference counter.
void qb_ipcs_connection_unref (qb_ipcs_connection_t *c)
Decrement the connection's reference counter.
void qb_ipcs_disconnect (qb_ipcs_connection_t *c)
Disconnect from this client.
int32_t qb_ipcs_service_id_get (qb_ipcs_connection_t *c)
Get the service id related to this connection's service.
void qb_ipcs_context_set (qb_ipcs_connection_t *c, void *context)
Associate a 'user' pointer with this connection.
void * qb_ipcs_context_get (qb_ipcs_connection_t *c)
Get the context (set previously).
void * qb_ipcs_connection_service_context_get (qb_ipcs_connection_t *c)
Get the context previously set on the service backing this
connection.
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.
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.
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.
qb_ipcs_connection_t * qb_ipcs_connection_first_get (qb_ipcs_service_t
*pt)
Get the first connection.
qb_ipcs_connection_t * qb_ipcs_connection_next_get (qb_ipcs_service_t
*pt, qb_ipcs_connection_t *current)
Get the next connection.
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.
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 wether you want to accept a new connection.
The type of checks you should do are authentication, service
availabilty or process resource constraints.
Returns:
0 to accept or -errno to indicate a failure (sent back to the
client)
Note:
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:
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.
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)
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
enum qb_ipcs_rate_limit
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:
conn connection instance
uid the user id to set.
gid the group id to set.
mode the 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:
pt service instance
Returns:
first connection
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:
pt service instance
current current connection
Returns:
next connection
void qb_ipcs_connection_ref (qb_ipcs_connection_t * c)
Increment the connection's reference counter. Parameters:
c connection 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:
c connection 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_read clear stats after copying them into stats
c connection instance
Returns:
0 == ok; -errno to indicate a failure
struct qb_ipcs_connection_stats_2* qb_ipcs_connection_stats_get_2
(qb_ipcs_connection_t * c, int32_t clear_after_read) [read]
Get (and allocate) the connection statistics. Parameters:
clear_after_read clear stats after copying them into stats
c connection instance
Return values:
NULL if no memory or invalid connection
allocated statistics structure (user must free it).
void qb_ipcs_connection_unref (qb_ipcs_connection_t * c)
Decrement the connection's reference counter. Parameters:
c connection instance
void* qb_ipcs_context_get (qb_ipcs_connection_t * c)
Get the context (set previously). Parameters:
c connection 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:
context the point to associate with this connection.
c connection 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:
name for clients to connect to.
service_id an integer to associate with the service
type transport type.
handlers callbacks.
Returns:
the new service instance.
void qb_ipcs_destroy (qb_ipcs_service_t * s)
Destroy the IPC server. Parameters:
s service instance to destroy
void qb_ipcs_disconnect (qb_ipcs_connection_t * c)
Disconnect from this client. Parameters:
c connection instance
ssize_t qb_ipcs_event_send (qb_ipcs_connection_t * c, const void * data,
size_t size)
Send an asyncronous event message to the client. Parameters:
c connection instance
data the message to send
size the 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_event_sendv (qb_ipcs_connection_t * c, const struct iovec *
iov, size_t iov_len)
Send an asyncronous event message to the client. Parameters:
c connection instance
iov the iovec struct that points to the message to send
iov_len the 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.
void qb_ipcs_poll_handlers_set (qb_ipcs_service_t * s, struct
qb_ipcs_poll_handlers * handlers)
Set your poll callbacks. Parameters:
s service instance
handlers the handlers that you want ipcs to use.
void qb_ipcs_ref (qb_ipcs_service_t * s)
Increase the reference counter on the service object. Parameters:
s service instance
void qb_ipcs_request_rate_limit (qb_ipcs_service_t * s, enum
qb_ipcs_rate_limit rl)
Limit the incomming request rate. Parameters:
s service instance
rl the new rate
ssize_t qb_ipcs_response_send (qb_ipcs_connection_t * c, const void * data,
size_t size)
Send a response to a incomming request. Parameters:
c connection instance
data the message to send
size the 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 incomming request. Parameters:
c connection instance
iov the iovec struct that points to the message to send
iov_len the 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.
int32_t qb_ipcs_run (qb_ipcs_service_t * s)
run the new IPC server. Parameters:
s service instance
Returns:
0 == ok; -errno to indicate a failure. Service is destroyed on
failure.
void* qb_ipcs_service_context_get (qb_ipcs_service_t * s)
Get the context (set previously). Parameters:
s service 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:
s service instance
context the 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_read clear stats after copying them into stats
pt service instance
Returns:
0 == ok; -errno to indicate a failure
void qb_ipcs_unref (qb_ipcs_service_t * s)
Decrease the reference counter on the service object. Parameters:
s service instance
Author
Generated automatically by Doxygen for libqb from the source code.
Version 0.16.0 21 Nov 2013 qbipcs.h(3)
