Diffusion Apple API  6.3.3
Unified Client Library for iOS, tvOS and OS X / macOS
 All Classes Functions Variables Properties Pages
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 the ClientControl feature. When registering to receive session properties, special key values of allFixedProperties (PTDiffusionSession) and allUserProperties (PTDiffusionSession) 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, 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 Java's Locale class (ISO 3166 alpha-2 country code or UN M.49 numeric-3 area code). 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 Java's Locale class (ISO 639 alpha-2 or alpha-3 language code, or registered language subtags up to 8 alpha letters (for future enhancements)). 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 PTDiffusionRolesFromString 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 PTDiffusionSessionId::description.
$StartTime The session's start time in milliseconds since the epoch.
$Transport The session transport type. One of WEBSOCKET, HTTP_LONG_POLL, or OTHER.

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

Session properties are initially associated with a session as follows:

  1. When a client starts a new session, it can optionally propose user-defined session properties (see PTDiffusionMutableSessionConfiguration::properties). Session properties proposed in this way must be accepted by the authenticator. This safeguard prevents abuse by a rogue, unprivileged client.
  2. The server allocates all fixed property values.
  3. 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 VIEW_SESSION and MODIFY_SESSION permissions using the ClientControl feature. A privileged client can also modify its own session properties.

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