Diffusion C API  6.5.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
messaging.h File Reference

This feature provides a client session with request-response messaging capabilities that can be used to implement application services. More...

Data Structures

struct  svc_send_receiver_client_request_s
 Structure containing the information received and passed to a handler registered on a message path, including the message content. More...
 
struct  msg_receiver_registration_params_s
 Structure supplied when issuing a register_msg_handler() call. More...
 
struct  send_request_to_session_params_s
 Structure supplied when issuing a send_request_to_session() call. More...
 
struct  diffusion_request_handler_s
 Request handler structure required when creating an ADD_REQUEST_HANDLER_PARAMS_T More...
 
struct  add_request_handler_params_s
 Structure supplied when issuing a add_request_handler() call. More...
 
struct  send_request_to_filter_params_s
 Structure supplied when issuing a send_request_to_filter() call. More...
 
struct  send_request_params_s
 Structure supplied to a send_request() call. More...
 
struct  diffusion_request_stream_s
 Structure supplied when adding a request stream. More...
 

Macros

#define MSG_RECEIVER_REGISTRATION_HANDLERS
 Handlers for notification of registration of handler and message receipt.
 

Typedefs

typedef struct
DIFFUSION_REQUEST_CONTEXT_T 
DIFFUSION_REQUEST_CONTEXT_T
 Context information of the request received. More...
 
typedef struct
svc_send_receiver_client_request_s 
SVC_SEND_RECEIVER_CLIENT_REQUEST_T
 Structure containing the information received and passed to a handler registered on a message path, including the message content.
 
typedef int(* on_msg_receiver_registration_cb )(SESSION_T *session, void *context)
 Callback when a handler is registered with the server. More...
 
typedef int(* on_send_receiver_client_msg_cb )(SESSION_T *session, const SVC_SEND_RECEIVER_CLIENT_REQUEST_T *request, void *context)
 Callback when a message is received by a registered handler on a message path. More...
 
typedef struct
msg_receiver_registration_params_s 
MSG_RECEIVER_REGISTRATION_PARAMS_T
 Structure supplied when issuing a register_msg_handler() call.
 
typedef int(* request_on_response_cb )(DIFFUSION_DATATYPE response_datatype, const DIFFUSION_VALUE_T *response, void *context)
 Callback when a response to a request is received. More...
 
typedef struct
send_request_to_session_params_s 
SEND_REQUEST_TO_SESSION_PARAMS_T
 Structure supplied when issuing a send_request_to_session() call.
 
typedef int(* request_handler_on_request )(SESSION_T *session, DIFFUSION_DATATYPE request_datatype, const DIFFUSION_VALUE_T *request, const DIFFUSION_REQUEST_CONTEXT_T *request_context, const DIFFUSION_RESPONDER_HANDLE_T *handle, void *context)
 Callback when a request to a request handler has been received. More...
 
typedef int(* request_handler_on_active )(SESSION_T *session, const char *path, const DIFFUSION_REGISTRATION_T *registered_handler)
 Callback when a request handler is active. More...
 
typedef void(* request_handler_on_close )(void)
 Callback when a request handler is closed.
 
typedef int(* request_handler_on_error )(const DIFFUSION_ERROR_T *error)
 Callback when a request handler has encountered an error. More...
 
typedef struct
diffusion_request_handler_s 
DIFFUSION_REQUEST_HANDLER_T
 Request handler structure required when creating an ADD_REQUEST_HANDLER_PARAMS_T
 
typedef struct
add_request_handler_params_s 
ADD_REQUEST_HANDLER_PARAMS_T
 Structure supplied when issuing a add_request_handler() call.
 
typedef int(* filtered_request_number_sent )(int number_sent, void *context)
 Callback when a filtered request has been dispatched to a number of sessions. More...
 
typedef int(* filtered_request_on_response )(DIFFUSION_DATATYPE response_datatype, const DIFFUSION_VALUE_T *response, void *context)
 Callback when a response to a filtered request has been received. More...
 
typedef int(* filtered_request_on_response_error )(const SESSION_ID_T *session_id, const DIFFUSION_ERROR_T *error)
 Callback when a response results in an error. More...
 
typedef struct
send_request_to_filter_params_s 
SEND_REQUEST_TO_FILTER_PARAMS_T
 Structure supplied when issuing a send_request_to_filter() call.
 
typedef struct
send_request_params_s 
SEND_REQUEST_PARAMS_T
 Structure supplied to a send_request() call.
 
typedef int(* request_stream_on_request_cb )(SESSION_T *session, const char *path, DIFFUSION_DATATYPE request_datatype, const DIFFUSION_VALUE_T *request, const DIFFUSION_RESPONDER_HANDLE_T *responder_handle, void *context)
 Callback for a request stream when a request has been received. More...
 
typedef int(* request_stream_on_error_cb )(const DIFFUSION_ERROR_T *error)
 Callback when a request stream encounters an error. More...
 
typedef void(* request_stream_on_close_cb )(void)
 Callback for a request stream that has been closed.
 
typedef struct
diffusion_request_stream_s 
DIFFUSION_REQUEST_STREAM_T
 Structure supplied when adding a request stream.
 

Functions

SESSION_ID_Tdiffusion_request_context_get_session_id (const DIFFUSION_REQUEST_CONTEXT_T *request_context)
 Return a copy of the request context's session ID. More...
 
char * diffusion_request_context_get_path (const DIFFUSION_REQUEST_CONTEXT_T *request_context)
 Return a copy of the request context's request path. More...
 
HASH_Tdiffusion_request_context_get_session_properties (const DIFFUSION_REQUEST_CONTEXT_T *request_context)
 Return a copy of the request context's session properties. More...
 
void send_request_to_session (SESSION_T *session, SEND_REQUEST_TO_SESSION_PARAMS_T params)
 Send a request to a specific session. More...
 
void send_request_to_filter (SESSION_T *session, SEND_REQUEST_TO_FILTER_PARAMS_T params)
 Send a request via a filter. More...
 
void add_request_handler (SESSION_T *session, ADD_REQUEST_HANDLER_PARAMS_T params)
 Add a server registered request handler. More...
 
void send_request (SESSION_T *session, SEND_REQUEST_PARAMS_T params)
 Send a request to a path. More...
 
DIFFUSION_REQUEST_STREAM_Tset_request_stream (SESSION_T *session, const char *path, DIFFUSION_DATATYPE request_datatype, DIFFUSION_DATATYPE response_datatype, const DIFFUSION_REQUEST_STREAM_T *request_stream)
 Set a request stream to handle requests to a specified path. More...
 
DIFFUSION_REQUEST_STREAM_Tremove_request_stream (SESSION_T *session, const char *request_path)
 Remove a request stream bound to a specified path. More...
 

Detailed Description

This feature provides a client session with request-response messaging capabilities that can be used to implement application services.

Messaging feature.

Request-response messaging allows a session to send requests to other sessions. Each receiving session provides a corresponding response, which is returned to the sending session. Each request and response carries an application provided value.

The method used to send a request determines which sessions will receive it. Each request is routed using the provided message path – an application provided string. Two addressing schemes are provided: unaddressed requests and addressed requests.

Unaddressed requests

A session can provide an application service by implementing a handler and registering it with the server. This is somewhat similar to implementing a REST service, except that interactions between the sender and receiver are asynchronous.

Unaddressed requests sent using send_request are routed by the server to a handler that has been pre-registered by another session, and matches the message path.

Handlers are registered with addRequestHandler. Each session may register at most one handler for a given message path. Optionally, one or more session property names can be provided (see session.h for a full description of session properties), in which case the values of the session properties for each recipient session will be returned along with its response. To add a request handler, the control client session must have GLOBAL_PERMISSION_REGISTER_HANDLER permission. If registering to receive session property values, the session must also have GLOBAL_PERMISSION_VIEW_SESSION permission.

Routing works as follows:

  1. The session sends the request, providing the message path, the request value and data type, and the expected response type.
  2. The server uses the message path to apply access control. The sender must have the PATH_PERMISSION_SEND_TO_MESSAGE_HANDLER path permission for the message path, or the request will be rejected.
  3. The server uses the message path to select a pre-registered handler and route the request to the appropriate recipient session. The server will consider all registered handlers and select one registered for the most specific path. If multiple sessions have registered a handler registered for a path, one will be chosen arbitrarily. If there is no registered handler matching the message path, the request will be rejected.
  4. Otherwise, the server forwards the request to one of the sessions registered to handle the message path. The message path is also passed to the recipient session, providing a hierarchical context.
  5. The recipient session processes the request and returns a response to the server, which forwards the response to the sending session.

Registration works across a cluster of servers. If no matching handler is registered on the server to which the sending session is connected, the request will be routed to another server in the cluster that has one.

Addressed requests

Addressed requests provide a way to perform actions on a group of sessions, or to notify sessions of one-off events (for repeating streams of events, use a topic instead).

An addressed request can be sent to a set of sessions using send_request_to_filter. For the details of session filters, see session.h. Sending a request to a filter will match zero or more sessions. Each response received will be passed to the provided callbacks in SEND_REQUEST_TO_FILTER_PARAMS_T. As a convenience, an addressed request can be sent a specific session using send_request_to_session that accepts a session id.

Sending an addressed request requires PATH_PERMISSION_SEND_TO_SESSION permission.

If the sending session is connected to a server belonging to a cluster, the recipient sessions can be connected to other servers in the cluster. The filter will be evaluated against all sessions hosted by the cluster.

To receive addressed requests, a session must set up a local request stream to handle the specific message path, using set_request_stream. When a request is received for the message path, the DIFFUSION_REQUEST_STREAM_T.request_stream_on_request_cb method on the stream is triggered. The session should respond using the provided DIFFUSION_RESPONDER_HANDLE_T. Streams receive a DIFFUSION_REQUEST_STREAM_T.request_stream_on_close_cb callback when unregistered and a DIFFUSION_REQUEST_STREAM_T.request_stream_on_error_cb callback if the session is closed.

If a request is sent to a session that does not have a matching stream for the message path, an error will be returned to the sending session.

Typedef Documentation

Context information of the request received.

Request path, session ID and session properties

typedef int(* filtered_request_number_sent)(int number_sent, void *context)

Callback when a filtered request has been dispatched to a number of sessions.

Parameters
number_sentThe number of requests sent to sessions.
contextUser supplied context passed in from SEND_REQUEST_TO_FILTER_PARAMS_T.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* filtered_request_on_response)(DIFFUSION_DATATYPE response_datatype, const DIFFUSION_VALUE_T *response, void *context)

Callback when a response to a filtered request has been received.

Parameters
response_datatypeDatatype of the response.
responseResponse as a DIFFUSION_VALUE_T.
contextUser supplied context passed in from SEND_REQUEST_TO_FILTER_PARAMS_T.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* filtered_request_on_response_error)(const SESSION_ID_T *session_id, const DIFFUSION_ERROR_T *error)

Callback when a response results in an error.

Parameters
session_idThe session id of the session which responded with an error.
errorThe response error. The context will be the user supplied context passed in from SEND_REQUEST_TO_FILTER_PARAMS_T.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_msg_receiver_registration_cb)(SESSION_T *session, void *context)

Callback when a handler is registered with the server.

Parameters
sessionThe currently active session.
contextUser-supplied context from the initial register_msg_handler() call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_send_receiver_client_msg_cb)(SESSION_T *session, const SVC_SEND_RECEIVER_CLIENT_REQUEST_T *request, void *context)

Callback when a message is received by a registered handler on a message path.

Parameters
sessionThe currently active session.
requestDetails about the incoming message, and the message itself.
contextUser-supplied context from the initial register_msg_handler() call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* request_handler_on_active)(SESSION_T *session, const char *path, const DIFFUSION_REGISTRATION_T *registered_handler)

Callback when a request handler is active.

Parameters
sessionThe currently active session.
pathThe path request handler is bound to.
registered_handlerThe registered handler
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* request_handler_on_error)(const DIFFUSION_ERROR_T *error)

Callback when a request handler has encountered an error.

Parameters
errorThe received error.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* request_handler_on_request)(SESSION_T *session, DIFFUSION_DATATYPE request_datatype, const DIFFUSION_VALUE_T *request, const DIFFUSION_REQUEST_CONTEXT_T *request_context, const DIFFUSION_RESPONDER_HANDLE_T *handle, void *context)

Callback when a request to a request handler has been received.

Parameters
sessionThe currently active session.
request_datatypeThe request datatype.
requestThe request.
request_contextThe request context.
handleThe responder handle. Used when a response is dispatched with respond_to_request.
contextUser supplied context.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* request_on_response_cb)(DIFFUSION_DATATYPE response_datatype, const DIFFUSION_VALUE_T *response, void *context)

Callback when a response to a request is received.

Parameters
response_datatypeDatatype of the response.
responseResponse as a DIFFUSION_VALUE_T.
contextUser supplied context passed in from SEND_REQUEST_TO_SESSION_PARAMS_T.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* request_stream_on_error_cb)(const DIFFUSION_ERROR_T *error)

Callback when a request stream encounters an error.

Parameters
errorThe error received on the request stream.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* request_stream_on_request_cb)(SESSION_T *session, const char *path, DIFFUSION_DATATYPE request_datatype, const DIFFUSION_VALUE_T *request, const DIFFUSION_RESPONDER_HANDLE_T *responder_handle, void *context)

Callback for a request stream when a request has been received.

Parameters
sessionThe session.
pathPath the request was received on.
request_datatypeThe request's datatype.
requestThe request.
responder_handleThe responder handle used when dispatching a response with respond_to_request. If the responder handle is required outside the scope of this function, use responder_handle_dup to copy it and use where necessary. This can be freed with responder_handle_free.
contextUser supplied context passed in from the request stream.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.

Function Documentation

void send_request_to_filter ( SESSION_T session,
SEND_REQUEST_TO_FILTER_PARAMS_T  params 
)

Send a request via a filter.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
paramsParameters defining the request to send a request via a filter.