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

Functions
SESSION_T *	session_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.

SESSION_T *	session_create_with_user_context (const char url_str, const char principal, CREDENTIALS_T credentials, SESSION_LISTENER_T listener, RECONNECTION_STRATEGY_T reconnection_strategy, void user_context, DIFFUSION_ERROR_T *error)
	Create a new session and synchronously open a connection to the Diffusion server at the endpoint specified by the URL.

SESSION_T *	session_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`.

SESSION_T *	session_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.

SESSION_T *	session_create_async_with_user_context (const char url_str, const char principal, CREDENTIALS_T credentials, SESSION_LISTENER_T listener, RECONNECTION_STRATEGY_T reconnection_strategy, SESSION_CREATE_CALLBACK_T callbacks, void user_context, DIFFUSION_ERROR_T error)
	Create a new session, but do not wait for the connection handshake to be performed.

SESSION_T *	session_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`.

void	session_free (SESSION_T *session)
	Free memory associated with a session.

int	session_close (SESSION_T session, DIFFUSION_ERROR_T error)
	Stop accepting messages from a Diffusion server and close the connection.

SESSION_STATE_T	session_state_get (SESSION_T *session)
	Returns the current session state.

CONNECTION_RESPONSE_CODE_T	session_connection_response_code (SESSION_T *session)
	Returns the last connection response code.

const char *	session_state_as_string (const SESSION_STATE_T state)
	Returns a human-readable representation of the session state.

int	session_is_connected (const SESSION_T *session)
	Determines if a session is connected to a server.

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.

int	session_is_closed (const SESSION_T *session)
	Determines if a session is closed.

char *	session_id_to_string (const SESSION_ID_T *session_id)
	Takes a session ID and produces a human-readable string.

SESSION_ID_T *	session_id_create_from_string (const char *str)
	Given a session id in string form, this function returns it to the internal structure form.

void	session_id_free (SESSION_ID_T *session_id)
	Free memory associated with a session ID structure.

int	session_id_cmp (const SESSION_ID_T s1, const SESSION_ID_T s2)
	Compare two session IDs.

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.

Detailed Description

Functions relating to a session and session management.

Create a new session metric collector using the values currently known by the builder.

A client session to a server or cluster of servers.

A new session can be created by connecting to a server using session_create_with_session_factory, specifying the server URL. There is also a non-blocking variant session_create_async_with_session_factory. The session factory can be configured to control the behavior the session.

The session provides a variety of operations to the application. These are grouped into feature headers, such as topics.h and messaging.h.

Session lifecycle

Each session is managed by a server. The server assigns the session a unique identity, and manages the session's topic subscriptions, security details, and session properties.

A session can be terminated using session_close(). A session may also be terminated by the server because of an error or a time out, or by other privileged sessions using the ClientControl feature.

A client can become disconnected from the server, and reconnect to the server without loss of the session. Reconnection can be configured using diffusion_session_factory_reconnection_strategy via the session factory. The server must be configured to allow reconnection.

If a session is connected to a server that belongs to a cluster with session replication enabled, and then becomes disconnected, it will attempt to reconnect to the original server. A properly configured load balancer can detect that the original server is unavailable and re-route the reconnection request to a second server in the cluster. The second server can recover session data and continue the session. This process is known as "fail over". Unlike reconnection, in-flight messages can be lost during failover, and the application will be unsubscribed and re-subscribed to topics.

The current state of the session can be retrieved with session_state_get(). A listener can be registered when the session is created, which will be notified when the session state changes.

Session properties

For each session, the server stores a set of session properties that describe various attributes of the session.

There are two types of session property. Fixed properties are assigned by the server. User-defined properties are assigned by the application.

Many operations use session filter expressions that use session properties to select sessions.

A privileged client can monitor other sessions, including changes to their session properties, using a session properties listener. When registering to receive session properties, special key values of PROPERTIES_SELECTOR_ALL_FIXED_PROPERTIES and PROPERTIES_SELECTOR_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:

Key	Description
`$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`, `MQTT`, `PYTHON`, 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.
`$Environment`	The environment in which the client is running. For possible values see the user manual
`$GatewayType`	Gateway client type. Only set for gateway client sessions. If present it indicates the type of gateway client (e.g. Kafka).
`$GatewayId`	The identity of a gateway client session. Only present if the $GatewayType session property is present.
`$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.
`$MQTTClientId`	The MQTT client identifier. Only set for MQTT sessions. If present, the value of the `$ClientType` session property will be MQTT.
`$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`, `HTTP_LONG_POLL`, `TCP`, or `OTHER`.

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

Session properties are initially associated with a session as follows:

When a client starts a new session, it can optionally propose user-defined session properties (see diffusion_session_factory_property and diffusion_session_factory_properties). Session properties proposed in this way must be accepted by the authenticator. This safeguard prevents abuse by a rogue, unprivileged client.
The server allocates all fixed property values.
The new session is authenticated by registered authenticators. An authenticator that accepts a session can veto or change the user-defined session properties and add new user-defined session properties. The authenticator can also change certain fixed properties.

Once a session is established, its user-defined session properties can be modified by clients with GLOBAL_PERMISSION_VIEW_SESSION and GLOBAL_PERMISSION_MODIFY_SESSION permissions using diffusion_set_session_properties(). A privileged client can also modify its own session properties.

If a session re-authenticates (see change_principal()), the authenticator that allows the re-authentication can modify the user-defined session properties and a subset of the fixed properties as mentioned above.

Session filters

Session filters are a mechanism of addressing a set of sessions by the values of their session properties.

Session filters are specified using a Domain Specific Language (DSL). For a full and detailed description of the session filters DSL see the user manual.

Session locks

The actions of multiple sessions can be coordinated using session locks. See file session-lock.h.

Parameters

builder	the session metric collector builder
name	the name of the session metric collector
session_filter	the session filter indicating the sessions this collector should apply to. The format of a session properties filter is documented in {}

Returns: a new session metric collector if the operation was successful, NULL otherwise.

Since: 6.7

Deprecated:: since 6.8 and will be removed in a future release use diffusion_session_metric_collector_builder_create instead

Parameters

builder	the session metric collector builder
name	the name of the session metric collector
session_filter	the session filter indicating the sessions this collector should apply to. The format of a session properties filter is documented in {}
api_error	populated on API error. Can be NULL.

Returns: a new session metric collector if the operation was successful, NULL otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

Since: 6.8