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
Instance Methods | List of all members
PTDiffusionClientControlFeature Class Reference

Introduction

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).

Access control

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.

Accessing the feature

This feature may be obtained from a PTDiffusionSession session as follows:

   
       PTDiffusionClientControlFeature *clientControl = session.clientControl;
   
Since
6.5
Inheritance diagram for PTDiffusionClientControlFeature:
PTDiffusionFeature

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
PTDiffusionSessionsession
 

Method Documentation

- (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.

Parameters
listenerthe listener to be called with session notifications
requiredPropertiesa 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.
completionHandlera 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:

Since
6.5
- (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.

Parameters
requiredPropertiesa 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.
sessionIdidentifies the client session
completionHandlercalled with the response
Since
6.5
- (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.

Parameters
propertiesthe 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).
sessionIdidentifies the client session
completionHandlera 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:

Since
6.5
- (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.

Parameters
propertiesthe 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).
filterthe session filter
completionHandlera 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:

Since
6.5