Diffusion Apple API  6.5.1
Unified Client Library for iOS, tvOS and OS X / macOS
 All Classes Files Functions Variables Enumerations Enumerator Properties Pages
Session filters

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:

The unary not operator can be used to negate the following clause or an expression within parentheses:

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.

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 all operator matches all sessions.

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.

All operators are case insensitive.


The following are further examples of valid session filter expressions: