Diffusion Apple API
6.10.0
Unified Client Library for iOS, tvOS and OS X / macOS
|
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:
not 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 function PTDiffusionEscape
can be used to insert escape characters into a value.
The all
operator matches all sessions.
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 $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 PTDiffusionStringFromRoles
utility method.
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 has
operator can be used to check if a property is present. This is useful for determining if user-defined properties or optional fixed propereties have been set.
All operators are case insensitive.
The lists provided to in and hasRoles can optionally use square brackets and commas as delimiters. For example `$Country in ['UK','DE','FR']`.
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"]
hasRoles "operator" and not hasRoles "administrator"
has Department
all