qbipcs.h File Reference

Server IPC API. More...

#include <stdlib.h>
#include <sys/uio.h>
#include <qb/qbipc_common.h>
#include <qb/qbhdb.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 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)

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

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

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  )

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.

Examples:

ipcserver.c.

void qb_ipcs_destroy

(

qb_ipcs_service_t *

s

)

Destroy the IPC server.

Parameters

s	service instance to destroy

Examples:

ipcserver.c.

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.

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

s	service instance
handlers	the 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

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.

Examples:

ipcserver.c.

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.

Examples:

ipcserver.c.

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

Examples:

ipcserver.c.

void qb_ipcs_unref

(

qb_ipcs_service_t *

s

)

Decrease the reference counter on the service object.

Parameters

s	service instance