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

Functions relating to a session and session management. More...

Functions

SESSION_Tsession_create (const char *url_str, const char *principal, CREDENTIALS_T *credentials, SESSION_LISTENER_T *listener, RECONNECTION_STRATEGY_T *reconnection_strategy, DIFFUSION_ERROR_T *error)
 Create a new session and synchronously open a connection to the Diffusion server at the endpoint specified by the URL. More...
 
SESSION_Tsession_create_with_session_factory (const DIFFUSION_SESSION_FACTORY_T *session_factory, const char *url_str)
 Create a new session and synchronously open a connection to the Diffusion server with a DIFFUSION_SESSION_FACTORY_T. More...
 
SESSION_Tsession_create_async (const char *url_str, const char *principal, CREDENTIALS_T *credentials, SESSION_LISTENER_T *listener, RECONNECTION_STRATEGY_T *reconnection_strategy, SESSION_CREATE_CALLBACK_T *callbacks, DIFFUSION_ERROR_T *error)
 Create a new session, but do not wait for the connection handshake to be performed. More...
 
SESSION_Tsession_create_async_with_session_factory (const DIFFUSION_SESSION_FACTORY_T *session_factory, SESSION_CREATE_CALLBACK_T *callbacks, const char *url_str)
 Create a new session and asynchronously open a connection to the Diffusion server with a DIFFUSION_SESSION_FACTORY_T. More...
 
void session_free (SESSION_T *session)
 Free memory associated with a session. More...
 
int session_close (SESSION_T *session, DIFFUSION_ERROR_T *error)
 Stop accepting messages from a Diffusion server and close the connection. More...
 
SESSION_STATE_T session_state_get (SESSION_T *session)
 Returns the current session state. More...
 
CONNECTION_RESPONSE_CODE_T session_connection_response_code (SESSION_T *session)
 Returns the last connection response code. More...
 
const char * session_state_as_string (const SESSION_STATE_T state)
 Returns a human-readable representation of the session state. More...
 
int session_is_connected (const SESSION_T *session)
 Determines if a session is connected to a server. More...
 
int session_is_recovering (const SESSION_T *session)
 Determines if a session is in a recovering state, where it is trying to reconnect to a server. More...
 
int session_is_closed (const SESSION_T *session)
 Determines if a session is closed. More...
 
char * session_id_to_string (const SESSION_ID_T *session_id)
 Takes a session ID and produces a human-readable string. More...
 
SESSION_ID_Tsession_id_create_from_string (const char *str)
 Given a session id in string form, this function returns it to the internal structure form. More...
 
void session_id_free (SESSION_ID_T *session_id)
 Free memory associated with a session ID structure. More...
 
int session_id_cmp (const SESSION_ID_T s1, const SESSION_ID_T s2)
 Compare two session IDs. More...
 
TOPIC_HANDLER_T set_global_topic_handler (SESSION_T *session, const TOPIC_HANDLER_T handler)
 Sets the handler for topics received but not subscribed to. More...
 
int session_set_maximum_outbound_queue_size (SESSION_T *session, int size)
 Sets the maximum size of the outbound queue. More...
 

Detailed Description

Functions relating to a session and session management.

A privileged client can monitor other sessions, including changes to their session properties, using a session_properties_listener_register. When registering to receive session properties, special key values of ALL_FIXED_PROPERTIES and ALL_USER_PROPERTIES can be used.

Each property is identified by a key. Most properties have a single string value. The exception is the $Roles fixed property which has a set of string values.

Fixed properties are identified by keys with a '$' prefix. The available fixed session properties are:

$ClientIP The Internet address of the client in string format.

$ClientType The client type of the session. One of ANDROID, C, DOTNET, IOS, JAVA, JAVASCRIPT_BROWSER, or OTHER.

$Connector The configuration name of the server connector that the client connected to.

$Country The country code for the country where the client's Internet address was allocated (for example, NZ for New Zealand). Country codes are as defined by locale. If the country code could not be determined, this will be a zero length string.

$Language The language code for the official language of the country where the client's Internet address was allocated (for example, en for English). Language codes are as defined by locale. If the language could not be determined or is not applicable, this will be a zero length string.

$Latitude The client's latitude, if available. This will be the string representation of a floating point number and will be NaN if not available.

$Longitude The client's longitude, if available. This will be the string representation of a floating point number and will be NaN if not available.

$Principal The security principal associated with the client session.

$Roles Authorisation roles assigned to the session. This is a set of roles represented as quoted strings (for example, "role1","role2"). The utility method diffusion_string_to_roles can be used to parse the string value into a set of roles.

$ServerName The name of the server to which the session is connected.

$SessionId The session identifier. Equivalent to session_id_to_string.

$StartTime The session's start time in milliseconds since the epoch.

$Transport The session transport type. One of WEBSOCKET or HTTP_LONG_POLL or OTHER

All user-defined property keys are non-empty strings. The characters ' ', '', '', '
', '"', ''', '(', ')' are not allowed.