NAME

       qbipcs.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_tuid, gid_tgid, mode_tmode)
       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_tclear_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_tclear_after_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_tservice_id, enum qb_ipc_typetype,
       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_tsize)
       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_tiov_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_limitrl)
       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_tsize)
       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_tiov_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_tclear_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.