Diffusion C API  6.3.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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, 2015 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.

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

Enumerator
RECONNECTION_ATTEMPT_ACTION_START 

Reconnect should be attempted.

RECONNECTION_ATTEMPT_ACTION_ABORT 

Reconnect should be aborted.

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 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.