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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

typedef int(*	request_stream_on_error_cb) (const DIFFUSION_ERROR_T *error)
	Callback when a request stream encounters an error.

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_T *	diffusion_request_context_get_session_id (const DIFFUSION_REQUEST_CONTEXT_T *request_context)
	Return a copy of the request context's session ID.

char *	diffusion_request_context_get_path (const DIFFUSION_REQUEST_CONTEXT_T *request_context)
	Return a copy of the request context's request path.

HASH_T *	diffusion_request_context_get_session_properties (const DIFFUSION_REQUEST_CONTEXT_T *request_context)
	Return a copy of the request context's session properties.

void	send_request_to_session (SESSION_T *session, SEND_REQUEST_TO_SESSION_PARAMS_T params)
	Send a request to a specific session.

void	send_request_to_filter (SESSION_T *session, SEND_REQUEST_TO_FILTER_PARAMS_T params)
	Send a request via a filter.

void	add_request_handler (SESSION_T *session, ADD_REQUEST_HANDLER_PARAMS_T params)
	Add a server registered request handler.

void	send_request (SESSION_T *session, SEND_REQUEST_PARAMS_T params)
	Send a request to a path.

DIFFUSION_REQUEST_STREAM_T *	set_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.

DIFFUSION_REQUEST_STREAM_T *	remove_request_stream (SESSION_T session, const char request_path)
	Remove a request stream bound to a specified path.

Detailed Description

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:

The session sends the request, providing the message path, the request value and data type, and the expected response type.
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.
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.
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.
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

◆ DIFFUSION_REQUEST_CONTEXT_T

typedef struct DIFFUSION_REQUEST_CONTEXT_T DIFFUSION_REQUEST_CONTEXT_T

Context information of the request received.

Request path, session ID and session properties

◆ filtered_request_number_sent

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_sent	The number of requests sent to sessions.
context	User supplied context passed in from `SEND_REQUEST_TO_FILTER_PARAMS_T`.

Returns: HANDLER_SUCCESS or HANDLER_FAILURE.

◆ filtered_request_on_response

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_datatype	Datatype of the response.
response	Response as a `DIFFUSION_VALUE_T`.
context	User supplied context passed in from `SEND_REQUEST_TO_FILTER_PARAMS_T`.

Returns: HANDLER_SUCCESS or HANDLER_FAILURE.

◆ filtered_request_on_response_error

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_id	The session id of the session which responded with an error.
error	The 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.

◆ on_msg_receiver_registration_cb

typedef int(* on_msg_receiver_registration_cb) (SESSION_T *session, void *context)

Callback when a handler is registered with the server.

Parameters

session	The currently active session.
context	User-supplied context from the initial register_msg_handler() call.

Returns: HANDLER_SUCCESS or HANDLER_FAILURE.

◆ on_send_receiver_client_msg_cb

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

session	The currently active session.
request	Details about the incoming message, and the message itself.
context	User-supplied context from the initial register_msg_handler() call.

Returns: HANDLER_SUCCESS or HANDLER_FAILURE.

◆ request_handler_on_active

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

session	The currently active session.
path	The path request handler is bound to.
registered_handler	The registered handler

Returns: HANDLER_SUCCESS or HANDLER_FAILURE.

◆ request_handler_on_error

typedef int(* request_handler_on_error) (const DIFFUSION_ERROR_T *error)

Callback when a request handler has encountered an error.

Parameters

error The received error.

Returns: HANDLER_SUCCESS or HANDLER_FAILURE.

◆ request_handler_on_request

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

session	The currently active session.
request_datatype	The request datatype.
request	The request.
request_context	The request context.
handle	The responder handle. Used when a response is dispatched with `respond_to_request`.
context	User supplied context.

Returns: HANDLER_SUCCESS or HANDLER_FAILURE.

◆ request_on_response_cb

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_datatype	Datatype of the response.
response	Response as a `DIFFUSION_VALUE_T`.
context	User supplied context passed in from `SEND_REQUEST_TO_SESSION_PARAMS_T`.

Returns: HANDLER_SUCCESS or HANDLER_FAILURE.

◆ request_stream_on_error_cb

typedef int(* request_stream_on_error_cb) (const DIFFUSION_ERROR_T *error)

Callback when a request stream encounters an error.

Parameters

error The error received on the request stream.

Returns: HANDLER_SUCCESS or HANDLER_FAILURE.

◆ request_stream_on_request_cb

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

session	The session.
path	Path the request was received on.
request_datatype	The request's datatype.
request	The request.
responder_handle	The 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`.
context	User supplied context passed in from the request stream.

Returns: HANDLER_SUCCESS or HANDLER_FAILURE.

Function Documentation

◆ send_request_to_filter()

void send_request_to_filter	(	SESSION_T *	session,
		SEND_REQUEST_TO_FILTER_PARAMS_T	params
	)

Send a request via a filter.

Parameters

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

Data Structures

Macros

Typedefs

Functions

Detailed Description

Messaging feature.

Unaddressed requests

Addressed requests

Typedef Documentation

◆ DIFFUSION_REQUEST_CONTEXT_T

◆ filtered_request_number_sent

◆ filtered_request_on_response

◆ filtered_request_on_response_error

◆ on_msg_receiver_registration_cb

◆ on_send_receiver_client_msg_cb

◆ request_handler_on_active

◆ request_handler_on_error

◆ request_handler_on_request

◆ request_on_response_cb

◆ request_stream_on_error_cb

◆ request_stream_on_request_cb

Function Documentation

◆ send_request_to_filter()