session_types.h File Reference

Types to describe a session, its parameters and related functions. More...

Data Structures
struct	session_id_s
	Structure describing a session ID, which is a unique identifier used by Diffusion for tracking this client; it is also used on reconnection to attempt to restore existing session state. More...
struct	session_listener_s
	When a session changes state, a listener may be called to inform the client of the transition via the appropriate function pointer in this structure. More...
struct	handler_set_s
	A handler set is registered against a conversation id and contains function pointers to callback handlers related to that conversation. More...
struct	reconnection_args_repeating
struct	reconnection_strategy_s
	When connecting to Diffusion, a reconnection strategy can be employed which describes what to do if the connection fails. More...
struct	session_create_callback_s
	When creating a session which performs a connection to Diffusion asynchronously, these callbacks can be supplied and are invoked when the connection is made successfully, or an error occurs. More...
struct	session_s
	This is the session structure which is created to represent a single instance of connection (session) with Diffusion. More...

Typedefs
typedef struct session_id_s	SESSION_ID_T
	Structure describing a session ID, which is a unique identifier used by Diffusion for tracking this client; it is also used on reconnection to attempt to restore existing session state.
typedef int(*	TOPIC_HANDLER_T )(struct session_s *session, const TOPIC_MESSAGE_T *message)
	Standard topic handler callback. More...
typedef int(*	STREAM_MESSAGE_LISTENER_T )(struct session_s *session, const STREAM_MESSAGE_T *message, void *context)
	Message stream callback. More...
typedef int(*	ERROR_HANDLER_T )(struct session_s *session, const DIFFUSION_ERROR_T *error)
	Standard error handler callback. More...
typedef int(*	DISCARD_HANDLER_T )(struct session_s *session, void *context)
	Standard conversation discard handler callback. More...
typedef struct session_listener_s	SESSION_LISTENER_T
	When a session changes state, a listener may be called to inform the client of the transition via the appropriate function pointer in this structure.
typedef struct handler_set_s	HANDLER_SET_T
	A handler set is registered against a conversation id and contains function pointers to callback handlers related to that conversation. More...
typedef struct reconnection_strategy_s	RECONNECTION_STRATEGY_T
	When connecting to Diffusion, a reconnection strategy can be employed which describes what to do if the connection fails. More...
typedef struct session_create_callback_s	SESSION_CREATE_CALLBACK_T
	When creating a session which performs a connection to Diffusion asynchronously, these callbacks can be supplied and are invoked when the connection is made successfully, or an error occurs.
typedef struct session_s	SESSION_T
	This is the session structure which is created to represent a single instance of connection (session) with Diffusion.

Enumerations
enum	SESSION_STATE_T {   SESSION_STATE_UNKNOWN, CONNECTING, CONNECTED_INITIALISING, CONNECTED_ACTIVE,   RECOVERING_RECONNECT, RECOVERING_FAILOVER, CLOSED_BY_CLIENT, CLOSED_BY_SERVER,   CLOSED_FAILED }
	A session will move through different states during its lifecycle. More...
enum	RECONNECTION_ATTEMPT_ACTION_T { RECONNECTION_ATTEMPT_ACTION_START, RECONNECTION_ATTEMPT_ACTION_ABORT }

Variables
const uint32_t	DIFFUSION_DEFAULT_CONNECTION_TIMEOUT
	The time, in milliseconds, that a connection attempt will wait to be established before it is terminated. More...
const int	DIFFUSION_DEFAULT_RECONNECT_TIMEOUT
	The time, in milliseconds, that reconnection attempts will be retried. More...
const uint32_t	DIFFUSION_DEFAULT_WRITE_TIMEOUT
	The time, in milliseconds, that a blocking write will timeout after. More...
const uint32_t	DIFFUSION_DEFAULT_RECONNECT_DELAY
	The default delay between reconnection attempts, in milliseconds. More...
const uint32_t	DIFFUSION_MAXIMUM_MESSAGE_SIZE_MINIMUM
	The minimum max message size (in bytes). More...
const uint32_t	DIFFUSION_DEFAULT_MAXIMUM_QUEUE_SIZE
	The default maximum outbound queue size. More...
const uint32_t	DIFFUSION_DEFAULT_INPUT_BUFFER_SIZE
	The default input buffer size in bytes. More...
const uint32_t	DIFFUSION_DEFAULT_OUTPUT_BUFFER_SIZE
	The default output buffer size in bytes. More...
const char *const	DIFFUSION_DEFAULT_REQUEST_PATH
	The default request path. More...
const uint32_t	DIFFUSION_DEFAULT_RECOVERY_BUFFER_SIZE
	The default recovery buffer size. More...
const uint32_t	DIFFUSION_DEFAULT_RECONNECT_RETRY_COUNT
	The default number of reconnection attempts. More...

Detailed Description

Types to describe a session, its parameters and related functions.

Typedef Documentation

typedef int(* DISCARD_HANDLER_T)(struct session_s *session, void *context)

Standard conversation discard handler callback.

typedef int(* ERROR_HANDLER_T)(struct session_s *session, const DIFFUSION_ERROR_T *error)

Standard error handler callback.

typedef struct handler_set_s HANDLER_SET_T

A handler set is registered against a conversation id and contains function pointers to callback handlers related to that conversation.

Users should avoid populating or accessing this structure.

typedef struct reconnection_strategy_s RECONNECTION_STRATEGY_T

When connecting to Diffusion, a reconnection strategy can be employed which describes what to do if the connection fails.

It is recommended that a reconnection strategy is created using one of the factory functions, e.g. make_reconnection_strategy_repeating_attempt, as direct access to the fields in this structure is likely to be withdrawn in the future.

typedef int(* STREAM_MESSAGE_LISTENER_T)(struct session_s *session, const STREAM_MESSAGE_T *message, void *context)

Message stream callback.

typedef int(* TOPIC_HANDLER_T)(struct session_s *session, const TOPIC_MESSAGE_T *message)

Standard topic handler callback.

Enumeration Type Documentation

enum RECONNECTION_ATTEMPT_ACTION_T

Enumerator
RECONNECTION_ATTEMPT_ACTION_START	Reconnect should be attempted.
RECONNECTION_ATTEMPT_ACTION_ABORT	Reconnect should be aborted.

enum SESSION_STATE_T

A session will move through different states during its lifecycle.

This enumeration lists those possible states.

Enumerator
SESSION_STATE_UNKNOWN	Unknown.
CONNECTING	In the process of connecting to Diffusion.
CONNECTED_INITIALISING	Connected to Diffusion but not yet receiving data. (Deprecated).
CONNECTED_ACTIVE	Connected to Diffusion and receiving data.
RECOVERING_RECONNECT	Recovering from a connection error by attempting to reconnect to the same Diffusion server.
RECOVERING_FAILOVER	Deprecated: Recovering from a connection error by attempting to reconnect to a different Diffusion server.
CLOSED_BY_CLIENT	This session was closed by the client.
CLOSED_BY_SERVER	This session was closed by Diffusion.
CLOSED_FAILED	An error occurred which caused the connection to be lost.

Variable Documentation

const uint32_t DIFFUSION_DEFAULT_CONNECTION_TIMEOUT

The time, in milliseconds, that a connection attempt will wait to be established before it is terminated.

Default value is 2 seconds.

const uint32_t DIFFUSION_DEFAULT_INPUT_BUFFER_SIZE

The default input buffer size in bytes.

Default value is 131072.

const uint32_t DIFFUSION_DEFAULT_MAXIMUM_QUEUE_SIZE

The default maximum outbound queue size.

Default value is 1000.

const uint32_t DIFFUSION_DEFAULT_OUTPUT_BUFFER_SIZE

The default output buffer size in bytes.

Default value is 131072.

const uint32_t DIFFUSION_DEFAULT_RECONNECT_DELAY

The default delay between reconnection attempts, in milliseconds.

Default value is 5 seconds.

const uint32_t DIFFUSION_DEFAULT_RECONNECT_RETRY_COUNT

The default number of reconnection attempts.

This value is the result of DIFFUSION_DEFAULT_RECONNECT_TIMEOUT / DIFFUSION_DEFAULT_RECONNECT_DELAY, thus the default value is 12.

const int DIFFUSION_DEFAULT_RECONNECT_TIMEOUT

The time, in milliseconds, that reconnection attempts will be retried.

Default value is 60 seconds.

const uint32_t DIFFUSION_DEFAULT_RECOVERY_BUFFER_SIZE

The default recovery buffer size.

Default value is 128.

const char* const DIFFUSION_DEFAULT_REQUEST_PATH

The default request path.

Default path is "/diffusion".

const uint32_t DIFFUSION_DEFAULT_WRITE_TIMEOUT

The time, in milliseconds, that a blocking write will timeout after.

Default value is 2 seconds.

const uint32_t DIFFUSION_MAXIMUM_MESSAGE_SIZE_MINIMUM

The minimum max message size (in bytes).

This value is 1024.