 |
Diffusion C API
6.10.3
|
|
Diffusion C API
6.10.3
|
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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. 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_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. 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... | |
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.
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.
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. |
$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:
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. 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 are query expressions for session properties. They can be used to address a set of sessions based on their session properties. For example, it is possible to send a message to all sessions that satisfy a specified filter. Session filters are parsed and evaluated at the server.
A session filter expression consists of either a single clause, or multiple clauses connected by the binary operators and and or. The and operator takes precedence over or but parentheses can be used to override the precedence. For example:
Department is "Accounts" hasRoles ["operator" "trading desk"] Department is "Payroll" and Status is "Closed" (Department is "Accounts" or Department is "Payroll") and Status is "Closed The unary not operator can be used to negate the following clause or an expression within parentheses:
Department is "Payroll" not (Department is "Payroll" or Department is "Accounts" An equality clause has the form key operator value where key is the name of a session property and value is the property value. The supported operators are is or eq, both of which mean "equals", and ne which means "does not equal". Values are strings enclosed within single or double quotes. Special characters (", ' or \) can be included within the value by preceding with the escape character \. The utility method diffusion_escape() can be used to insert escape characters into a value.
The all operator matches all sessions.
The has operator can be used to check if a property is present. This is useful for determining whether a user-defined property or an optional fixed property is set for a session.
hasRoles is a special operator for querying the $Roles session property. A hasRoles clause has the form hasRoles ["role1" "role2" ... "roleN"]. The clause will match sessions that have all the specified authorisation roles. Each role is a string enclosed within either single or double quotes. Roles can be space or comma separated.
The in operator allows for the querying of a specific session property to see if it exists in a defined set. An example of this would to be filter all sessions from a set of countries, say Germany, France, and the UK. The query would be `$Country in 'UK','DE','FR'`.
The lists provided to in and hasRoles can optionally use square brackets and commas as delimiters. For example `$Country in ['UK','DE','FR']`.
The $Roles session property can also be queried with an equality clause, for example, $Roles eq '"admin","client"', but the hasRoles clause is usually more convenient. An equality clause will match sessions that have exactly the listed roles. In contrast, a hasRoles clause will match any sessions with the listed roles, regardless of whether they have other roles. The equality clause requires the value to be in the canonical form produced by the diffusion_roles_to_string() utility method.
All operators are case insensitive.
The following are further examples of valid session filter expressions:
$Principal is "Alice" Department is "Accounts" and $Country ne "US" $Language EQ "en" and $Country NE "US" not (Department is "Accounts" or Department is "Payroll") and $Country is "FR" Text is "xyz\"\\" hasRoles ["operator"] $Transport is "wss" and hasRoles ["accountancy" "administrator"] hasRoles ["operator"] and not hasRoles ["administrator"] $Version in {"6","7","8"} $Country in ['UK','DE','FR'] has Department all The actions of multiple sessions can be coordinated using session locks. See file session-lock.h.
| 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 {} |
diffusion_session_metric_collector_builder_create instead | 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. |
api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
1.8.5