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

Messaging feature. More...

Data Structures

struct  send_msg_params_s
 Structure supplied to a send_msg() 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...
 
struct  msg_listener_registration_params_s
 Structure supplied when registering a message listener. More...
 
struct  msg_listener_deregistration_params_s
 Structure supplied when deregistering a message listener. More...
 

Macros

#define SEND_MSG_HANDLERS
 User-supplied handlers that may be invoked in response to a send_msg() call.
 

Typedefs

typedef int(* on_send_msg_cb )(SESSION_T *session, void *context)
 Callback for send_msg() More...
 
typedef struct send_msg_params_s SEND_MSG_PARAMS_T
 Structure supplied to a send_msg() 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.
 
typedef struct
msg_listener_registration_params_s 
MSG_LISTENER_REGISTRATION_PARAMS_T
 Structure supplied when registering a message listener.
 
typedef struct
msg_listener_deregistration_params_s 
MSG_LISTENER_DEREGISTRATION_PARAMS_T
 Structure supplied when deregistering a message listener.
 

Functions

 DEPRECATED (void send_msg(SESSION_T *session, SEND_MSG_PARAMS_T params))
 Synchronously send a message to Diffusion via a path. 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...
 
 DEPRECATED (void register_msg_listener(SESSION_T *session, MSG_LISTENER_REGISTRATION_PARAMS_T params))
 Register to accept messages (not topic updates) that are sent to this session via a path. More...
 
 DEPRECATED (void deregister_msg_listener(SESSION_T *session, MSG_LISTENER_DEREGISTRATION_PARAMS_T params))
 Deregister a listener for a path. More...
 

Detailed Description

Messaging feature.

Typedef Documentation

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

Callback for send_msg()

Parameters
sessionThe current active session.
contextUser-supplied context from the initial registration call.
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

DEPRECATED ( void   send_msgSESSION_T *session, SEND_MSG_PARAMS_T params)

Synchronously send a message to Diffusion via a path.

Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release.

Messages are sent for a particular path. The message path acts as a context for the recipient which will see the message as having come 'from' the path as opposed to the actual originator. A topic with the path need not exist on the server; if one does exist, it is unaffected by messaging.

The calling session must have the SEND_TO_CLIENT permission for the message path.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
paramsParameters defining the message to be sent.
DEPRECATED ( void   register_msg_listenerSESSION_T *session, MSG_LISTENER_REGISTRATION_PARAMS_T params)

Register to accept messages (not topic updates) that are sent to this session via a path.

Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release.

Control clients may send messages directly to a client (or a group of clients) via a message path. Registering a listener for that path allows a client to receive these messages and have them be handled in a user-supplied function.

Specifying a NULL message path is a special case that catches all messages that do not have an explicit listener registered for it.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
paramsParameters defining the listener registration.
DEPRECATED ( void   deregister_msg_listenerSESSION_T *session, MSG_LISTENER_DEREGISTRATION_PARAMS_T params)

Deregister a listener for a path.

Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release.

If the message path specified in the params does not have a listener registered at it, then this function has no effect.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
paramsParameters describing the listener to be deregistered.