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 viewSession (PTDiffusionGlobalPermission) permission to be able to listen for notifications using addSessionPropertiesListener:forProperties:completionHandler: (PTDiffusionClientControlFeature) or getSessionProperties:forSession:completionHandler: (PTDiffusionClientControlFeature) of other sessions or listen for queue events. In addition, registerHandler (PTDiffusionGlobalPermission) 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 viewSession (PTDiffusionGlobalPermission) and modifySession (PTDiffusionGlobalPermission)` 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:

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...
(void)	- closeClientWithSessionId:completionHandler:
	Close a client session. More...
(void)	- closeClientWithFilter:completionHandler:
	Close all client sessions matching a given session filter. More...
(void)	- setQueueConflation:forSession:completionHandler:
	Sets the client session queue conflation policy. More...
(void)	- setQueueConflation:withFilter:completionHandler:
	Sets the queue conflation policy for all client sessions matching a given session filter. More...
(void)	- setQueueEventHandler:completionHandler:
	Register a delegate for client queue threshold events. More...

Additional Inherited Members
Properties inherited from PTDiffusionFeature
PTDiffusionSession *	session

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

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 occurred during the registration process. These may include:

• SessionClosed, if the session is closed
• HandlerConflict, if the session has already registered a queue event handler
• Security, if the session does not have registerHandler (PTDiffusionGlobalPermission) permission and/or viewSession (PTDiffusionGlobalPermission) permission.

Since

6.5

- (void) closeClientWithFilter:		(NSString *)	filter
completionHandler:		(NSInteger)	closedSessions
		(NSError *_Nullable error)	completionHandler

Close all client sessions matching a given session filter.

Parameters

filter	matches the set of client sessions to close. For details on specifying session filters see PTDiffusionSession.
completionHandler	a completion handler that is called then a response is received from the server. If the operation is successful, closedSessions will contain the number of client sessions that were closed and error will be nil.

Otherwise, the error will contain an error. These are the common reasons for failure:

• NoSuchSession, if the identified session was closed before the response was delivered
• Security, if the calling session does not have modifySession (PTDiffusionGlobalPermission) and viewSession (PTDiffusionGlobalPermission) permission
• SessionClosed, if the calling session is closed.

Since

6.6

- (void) closeClientWithSessionId:		(PTDiffusionSessionId *)	sessionId
completionHandler:		(NSError *_Nullable error)	completionHandler

Close a client session.

Parameters

sessionId	identifies the client session to close
completionHandler	a completion handler that is called then a response is received from the server. If the client session was closed successfully, the error will be nil

Otherwise, the error will contain an error. These are the common reasons for failure:

• NoSuchSession, if the identified session was closed before the response was delivered
• Security, if the calling session does not have modifySession (PTDiffusionGlobalPermission) and viewSession (PTDiffusionGlobalPermission) permission
• SessionClosed, if the calling session is closed.

Since

6.6

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

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

Since

6.5

- (void) setQueueConflation:		(BOOL)	conflate
forSession:		(PTDiffusionSessionId *)	sessionId
completionHandler:		(NSError *_Nullable error)	completionHandler

Sets the client session queue conflation policy.

Each session begins with conflation enabled or disabled based on the queue configuration of the connector it is using. This method allows conflation to be enabled or disabled for specific sessions at runtime.

Conflation is the process of merging or discarding topic updates queued for a session to reduce the server memory footprint and network data. Conflation needs to be enabled for a session and a policy configured for the topic to have an effect. Policies are configured on a per-topic basis using the conflationPropertyKey (PTDiffusionTopicSpecification).

Parameters

conflate	true to enable conflation, false to disable conflation
sessionId	identifies the client session
completionHandler	a completion handler that is called when a response is received from the server. If the conflation policy was updated for the identified session, the error will be nil.

Otherwise, the error will contain an error. These are the common reasons for failure:

• NoSuchSession, if the identified session was closed before the response was delivered
• Security, if the calling session does not have modifySession (PTDiffusionGlobalPermission) and viewSession (PTDiffusionGlobalPermission) permission
• SessionClosed, if the calling session is closed.

Since

6.6

- (void) setQueueConflation:		(BOOL)	conflate
withFilter:		(NSString *)	filter
completionHandler:		(NSInteger)	matchedSessions
		(NSError *_Nullable error)	completionHandler

Sets the queue conflation policy for all client sessions matching a given session filter.

Each session begins with conflation enabled or disabled based on the queue configuration of the connector it is using. This method allows conflation to be enabled or disabled for specific sessions at runtime.

Conflation is the process of merging or discarding topic updates queued for a session to reduce the server memory footprint and network data. Conflation needs to be enabled for a session and a policy configured for the topic to have an effect. Policies are configured on a per-topic basis using the conflationPropertyKey (PTDiffusionTopicSpecification).

Parameters

conflate	true to enable conflation, false to disable conflation
filter	matches the set of client sessions to close. For details on specifying session filters see PTDiffusionSession.
completionHandler	a completion handler that is called when a response is received from the server. If the conflation policy was updated for the identified session, the error will be nil.

Otherwise, the error will contain an error. These are the common reasons for failure:

• NoSuchSession, if the identified session was closed before the response was delivered
• Security, if the calling session does not have modifySession (PTDiffusionGlobalPermission) and viewSession (PTDiffusionGlobalPermission) permission
• SessionClosed, if the calling session is closed.

Since

6.6

- (void) setQueueEventHandler:		(id< PTDiffusionClientQueueEventListener >)	listener
completionHandler:		(PTDiffusionRegistration *)	registration
		(NSError *_Nullable error)	completionHandler

Register a delegate for client queue threshold events.

Each control session can register a single handler. When the handler is no longer required, it may be closed using the PTDiffusionRegistration provided by the completion handler. To set a different handler the current handler must first be closed. For each event, the server will select a single handler.

The control session may choose to act upon queue events for a session by activating conflation for the session.

Parameters

listener	the queue handler listener to set
completionHandler	a completion handler than returns when the listener has been registered, returning a PTDiffusionRegistration which can be used to unregister the listener.

If the registration is nil. This could mean an error has occurred during the registration process. These may include:

• SessionClosed, if the session is closed
• HandlerConflict, if the session has already registered a queue event handler
• Security, if the session does not have registerHandler (PTDiffusionGlobalPermission) permission and/or viewSession (PTDiffusionGlobalPermission) permission.

Since

6.6

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

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:

• NoSuchSession, if the identified session was closed before the response was delivered
• Security, if the calling session does not have modifySession (PTDiffusionGlobalPermission) and viewSession (PTDiffusionGlobalPermission) permission
• SessionClosed, if the calling session is closed.

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

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:

• NoSuchSession, if the identified session was closed before the response was delivered
• Security, if the calling session does not have modifySession (PTDiffusionGlobalPermission) and viewSession (PTDiffusionGlobalPermission) permission
• SessionClosed, if the calling session is closed.

Since

6.5