 |
Diffusion Apple API
6.5.12
Unified Client Library for iOS, tvOS and OS X / macOS
|
|
Diffusion Apple API
6.5.12
Unified Client Library for iOS, tvOS and OS X / macOS
|
The Client Control feature provides the ability for a client session to control other client sessions.
It allows for notifications of client sessions starting and closing as well as the ability to manage client sessions (forcibly closing them etc).
A session must have VIEW_SESSION permission to be able to listen for notifications using setSessionPropertiesEventListener or getSessionProperties of other sessions or listen for queue events. In addition, REGISTER_HANDLER permission is required to set a session properties listener or queue event handler.
In order to perform operations that change a session's state (such as throttling, conflating, or closing the session, or changing roles), both VIEW_SESSION and MODIFY_SESSION permission is required.
This feature may be obtained from a PTDiffusionSession session as follows:
PTDiffusionClientControlFeature *clientControl = session.clientControl;
Instance Methods | |
| (void) | - addSessionPropertiesListener:forProperties:completionHandler: |
| Register a listener that will be notified when client sessions are opened, disconnected, reconnected, closed or when selected session property values are updated. More... | |
| (void) | - getSessionProperties:forSession:completionHandler: |
| Query the server for property values of a specified client session. More... | |
| (void) | - setSessionProperties:forSession:completionHandler: |
| Send a request to the server to change the user-defined session properties for a session. More... | |
| (void) | - setSessionProperties:usingFilter:completionHandler: |
| Send a request to the server to set all sessions that satisfy a session filter with the new user-defined session properties. More... | |
Additional Inherited Members | |
 Properties inherited from PTDiffusionFeature | |
| PTDiffusionSession * | session |
| - (void) addSessionPropertiesListener: | (id< PTDiffusionSessionPropertiesDelegate >) | listener | |
| forProperties: | (NSArray< NSString * > *) | requiredProperties | |
| completionHandler: | (PTDiffusionSessionPropertiesListenerRegistration *_Nullable) | registration | |
| (NSError *_Nullable error) | completionHandler | ||
Register a listener that will be notified when client sessions are opened, disconnected, reconnected, closed or when selected session property values are updated.
When a listener is first set, it will be called with the required properties of all currently open client sessions. The amount of data transferred from the server is proportional to the number of connected clients and is potentially large. The amount of data can be reduced using requiredProperties parameter.
Each control session can register a single listener. When the listener is no longer required, it may be closed using the PTDiffusionSessionPropertiesListenerRegistration provided by the completionHandler. To change the listener, the previous listener must first be closed.
The requiredProperties parameter is used to select the property values required.
The requested property set controls the level of detail provided and whether the listener is called for updates to sessions. If no properties are requested, the listener is not called when session properties are updated.
| listener | the listener to be called with session notifications |
| requiredProperties | a list of required property keys. See PTDiffusionSession for a full list of available fixed property keys. To request no properties, supply an empty list. To request all fixed properties, include allFixedProperties (PTDiffusionSession) as an entry. In this case any other fixed property keys would be ignored. To request all user properties, include allUserProperties (PTDiffusionSession) as an entry. In this case any other user properties are ignored. |
| completionHandler | a completion handler than returns when the listener has been registered, returning a PTDiffusionSessionPropertiesListenerRegistration which can be used to unregister the listener. |
If the registration is nil. This could mean an error has occured during the registration process. These may include:
registerHandler (PTDiffusionGlobalPermission) permission and/or viewSession (PTDiffusionGlobalPermission) permission.| - (void) getSessionProperties: | (NSArray< NSString * > *) | requiredProperties | |
| forSession: | (PTDiffusionSessionId *) | sessionId | |
| completionHandler: | (PTDiffusionGetSessionPropertiesResult *_Nullable) | result | |
| (NSError *_Nullable error) | completionHandler | ||
Query the server for property values of a specified client session.
| requiredProperties | a list of required property keys. See PTDiffusionSession for a full list of available fixed property keys. To request no properties, supply an empty list. To request all fixed properties, include allFixedProperties (PTDiffusionSession) as a key. In this case any other fixed property keys would be ignored. To request all user properties, include allUserProperties (PTDiffusionSession) as a key. In this case any other user properties are ignored. |
| sessionId | identifies the client session |
| completionHandler | called with the response |
| - (void) setSessionProperties: | (NSDictionary< NSString *, NSString * > *) | properties | |
| forSession: | (PTDiffusionSessionId *) | sessionId | |
| completionHandler: | (PTDiffusionSetSessionPropertiesResult *_Nullable) | result | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request to the server to change the user-defined session properties for a session.
It is also permissible to change the values of the following fixed session properties :-
$Country - will be normalised to upper case $Language - will be normalised to lower case $Latitude - Invalid value will be set to "NaN" $Longitude - Invalid value will be set to "NaN"
If values are provided for any other fixed session properties they will be ignored.
| properties | the properties to change. Each entry in the map is a property name and the new value. If the value is [NSNull null], any existing property with that name will be removed (unless it is a fixed property). Otherwise if the property name does not match any existing property, that entry will be added as a new property (although properties starting with $ will be ignored). |
| sessionId | identifies the client session |
| completionHandler | a completion handler that is called when a response is received from the server, returning the maps of session properties that were added or updated. |
If the session properties were updated, the result will contain a map of properties that changed with their previous values. If no properties were changed, the map will be empty. If any new properties were added, the values in the map will be [NSNull null] to indicate that they do not have an old value.
Otherwise, the error will contain an error. Common reasons for failure:
modifySession (PTDiffusionGlobalPermission) and viewSession (PTDiffusionGlobalPermission) permission| - (void) setSessionProperties: | (NSDictionary< NSString *, NSString * > *) | properties | |
| usingFilter: | (NSString *) | filter | |
| completionHandler: | (NSInteger) | matches | |
| (NSError *_Nullable error) | completionHandler | ||
Send a request to the server to set all sessions that satisfy a session filter with the new user-defined session properties.
It is also permissible to change the values of the following fixed session properties :-
$Country - will be normalised to upper case $Language - will be normalised to lower case $Latitude - Invalid value will be set to "NaN" $Longitude - Invalid value will be set to "NaN"
If values are provided for any other fixed session properties they will be ignored.
| properties | the properties to change. Each entry in the map is a property name and the new value. If the value is [NSNull null], any existing property with that name will be removed (unless it is a fixed property). Otherwise if the property name does not match any existing property, that entry will be added as a new property (although properties starting with $ will be ignored). |
| filter | the session filter |
| completionHandler | a completion handler that is called when a response is received from the server, returning the total number of sessions that were updated with the filter. |
If matches is 0, the filter has not selected any session If matches is -1, an error has occurred. These are the common reasons for failure:
modifySession (PTDiffusionGlobalPermission) and viewSession (PTDiffusionGlobalPermission) permission
1.8.5