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.

Copyright © 2014, 2021 Push Technology Ltd., All Rights Reserved.

Use is subject to license terms.

NOTICE: All information contained herein is, and remains the property of Push Technology. The intellectual and technical concepts contained herein are proprietary to Push Technology and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or copyright law.

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.