NAME

       qbipcs.h - Server IPC API.

SYNOPSIS

       #include <sys/types.h>
       #include <sys/uio.h>
       #include <qb/qbipc_common.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 whether 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 incoming request 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.
       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.
       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.
       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.
       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.
       int32_t qb_ipcs_connection_get_buffer_size (qb_ipcs_connection_t *conn)
           Retrieve the connection ipc buffer size.
       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.

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 repeatedly 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)
   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

   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:
           conn connection 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:
           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)
       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

   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:
           s ipc server instance
           max_buf_size represented in bytes

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

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

           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()

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

           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()

   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.