Interface IClientControl

This feature provides the ability for a client session to control other client sessions.

Inherited Members

Namespace: PushTechnology.ClientInterface.Client.Features.Control.Clients

Assembly: Diffusion.Client.dll

Syntax

public interface IClientControl : IFeature

Remarks

It allows for notifications of client session events as well as the ability to manage clients (forcibly closing them etc).

It also provides the ability to monitor session locks.

Access Control

A session must have VIEW_SESSION permission to be able to listen for notifications using AddSessionEventListenerAsync(ISessionEventStream, ISessionEventParameters) or SetSessionPropertiesListener(ISessionPropertiesListener, String[]) or GetSessionPropertiesAsync(ISessionId, List<String>) of sessions or listen for SetQueueEventHandler(IQueueEventHandler) queue events.

In addition REGISTER_HANDLER permission is required to set a session event listener, a session property listener, or queue event handler.

In order to perform operations that change a specific session's state (such as conflating, closing sessions, or changing roles), MODIFY_SESSION permission is required.

Accessing the feature

This feature may be obtained from an ISession as follows:

var clientControl = session.ClientControl;

Added in version 5.0.

Methods

AddSessionEventListenerAsync(ISessionEventStream, ISessionEventParameters)

Registers a listener that will be notified of ISessionEventStreamEvent client session events.

Declaration

Task<IRegistration> AddSessionEventListenerAsync(ISessionEventStream listener, ISessionEventParameters parameters)

Parameters

Type	Name	Description
ISessionEventStream	listener	The listener to be called with session event notifications.
ISessionEventParameters	parameters	A ISessionEventParameters object defining the level of event detail required.

Returns

Type	Description
System.Threading.Tasks.Task<IRegistration>	A `Task` that completes when the listener has been registered, returning a IRegistration which can be used to unregister the listener.

Remarks

These events may occur when a client session is opened, becomes disconnected, reconnects, fails over, or is closed. Events may also occur if any of the session properties of the client session change as a result of a call to SetSessionPropertiesAsync(ISessionId, Dictionary<String, String>).

When a listener is first added, by default, it will be called with STATE events for all currently open sessions. The amount of data transferred from the server is proportional to the number of connected clients and is potentially large, especially if session properties are requested. To mitigate this the caller can choose to only receive events for sessions started after a specified time (e.g. from now), in which case events will only be received for sessions that start after that time.

A control session can register any number of listeners with different parameters, but the cost in network traffic should be carefully considered.

When a listener is no longer required, it may be closed using the IRegistration provided by the Task result.

The parameters parameter is used to define the level of event detail required.

Exceptions

Type	Condition
System.ArgumentNullException	If `listener` or `parameters` is `null`.
SessionSecurityException	The calling session does not have the REGISTER_HANDLER and VIEW_SESSION permissions. Thrown by the returned `Task`.
SessionClosedException	The calling session is closed. Thrown by the returned `Task`.

AddSessionEventListenerAsync(ISessionEventStream, ISessionEventParameters, CancellationToken)

Registers a listener that will be notified of ISessionEventStreamEvent client session events.

Declaration

Task<IRegistration> AddSessionEventListenerAsync(ISessionEventStream listener, ISessionEventParameters parameters, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ISessionEventStream	listener	The listener to be called with session event notifications.
ISessionEventParameters	parameters	A ISessionEventParameters object defining the level of event detail required.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<IRegistration>	A `Task` that completes when the listener has been registered, returning a IRegistration which can be used to unregister the listener.

Remarks

A control session can register any number of listeners with different parameters, but the cost in network traffic should be carefully considered.

When a listener is no longer required, it may be closed using the IRegistration provided by the Task result.

The parameters parameter is used to define the level of event detail required.

Exceptions

Type	Condition
System.ArgumentNullException	If `listener` or `parameters` is `null`.
SessionSecurityException	The calling session does not have the REGISTER_HANDLER and VIEW_SESSION permissions. Thrown by the returned `Task`.
SessionClosedException	The calling session is closed. Thrown by the returned `Task`.

ChangeRolesAsync(ISessionId, ICollection<String>, ICollection<String>)

Changes the assigned roles of another session.

Declaration

Task<object> ChangeRolesAsync(ISessionId sessionId, ICollection<string> rolesToRemove, ICollection<string> rolesToAdd)

Parameters

Type	Name	Description
ISessionId	sessionId	The client session for which the change will be applied.
System.Collections.Generic.ICollection<System.String>	rolesToRemove	The collection of roles to be removed from the session.
System.Collections.Generic.ICollection<System.String>	rolesToAdd	The collection of roles to be added to the session.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The `Task` representing the current operation.

Remarks

If the task completes successfully, the Task result will be null.

Initially a session has a set of roles assigned during authentication. The set of assigned roles can be obtained from the session's $Roles session property.

When a session's assigned roles change, its $Roles property changes accordingly. Changing the assigned roles can change the READ_TOPIC permissions granted to the session. The session's subscriptions will be updated accordingly.

The same role must not occur in both rolesToRemove and rolesToAdd sets. Either set can be an empty set but not both.

Exceptions

Type	Condition
System.ArgumentNullException	If `sessionId`, `rolesToAdd`, or `rolesToRemove` is `null`.
System.ArgumentException	Both `rolesToAdd` and `rolesToRemove` are empty or contain the same role(s).
System.ArgumentException	If `sessionId` is an invalid session identifier.
NoSuchSessionException	There is no session with the given `sessionId`. Thrown by the returned `Task`.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission.
SessionClosedException	The session is closed. Thrown by the returned `Task`.

ChangeRolesAsync(ISessionId, ICollection<String>, ICollection<String>, CancellationToken)

Changes the assigned roles of another session.

Declaration

Task<object> ChangeRolesAsync(ISessionId sessionId, ICollection<string> rolesToRemove, ICollection<string> rolesToAdd, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ISessionId	sessionId	The client session for which the change will be applied.
System.Collections.Generic.ICollection<System.String>	rolesToRemove	The collection of roles to be removed from the session.
System.Collections.Generic.ICollection<System.String>	rolesToAdd	The collection of roles to be added to the session.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The `Task` representing the current operation.

Remarks

If the task completes successfully, the Task result will be null.

Initially a session has a set of roles assigned during authentication. The set of assigned roles can be obtained from the session's $Roles session property.

The same role must not occur in both rolesToRemove and rolesToAdd sets. Either set can be an empty set but not both.

Exceptions

Type	Condition
System.ArgumentNullException	If `sessionId`, `rolesToAdd`, or `rolesToRemove` is `null`.
System.ArgumentException	Both `rolesToAdd` and `rolesToRemove` are empty or contain the same role(s).
System.ArgumentException	If `sessionId` is an invalid session identifier.
NoSuchSessionException	There is no session with the given `sessionId`. Thrown by the returned `Task`.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission.
SessionClosedException	The session is closed. Thrown by the returned `Task`.

ChangeRolesAsync(String, ICollection<String>, ICollection<String>)

Allows a session to change the assigned roles of all sessions that satisfy a given session filter.

Declaration

Task<int> ChangeRolesAsync(string filter, ICollection<string> rolesToRemove, ICollection<string> rolesToAdd)

Parameters

Type	Name	Description
System.String	filter	The filter of client sessions for which the change will be applied.
System.Collections.Generic.ICollection<System.String>	rolesToRemove	The collection of roles to be removed from the session.
System.Collections.Generic.ICollection<System.String>	rolesToAdd	The collection of roles to be added to the session.

Returns

Type	Description
System.Threading.Tasks.Task<System.Int32>	The `Task` representing the current operation.

Remarks

If the task completes successfully, the Task result will be the number of sessions that have matched the filter and for which the specified role changes have been applied.

Initially a session has a set of roles assigned during authentication. A current roles set can be obtained from the $Roles session property.

When a set of session roles changes, its $Roles property changes accordingly. As a role can constrain 'topic' permissions, session subscriptions are re-evaluated based on the new roles set.

The same role must not occur in both rolesToRemove and rolesToAdd sets. Either set can be an empty set but not both.

Exceptions

Type	Condition
System.ArgumentNullException	If `filter`, `rolesToAdd`, or `rolesToRemove` is `null`.
System.ArgumentException	Both `rolesToAdd` and `rolesToRemove` are empty or contain the same role(s).
InvalidFilterException	The `filter` could not be parsed. Thrown by the returned `Task`.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission.
SessionClosedException	The session is closed. Thrown by the returned `Task`.

ChangeRolesAsync(String, ICollection<String>, ICollection<String>, CancellationToken)

Allows a session to change the assigned roles of all sessions that satisfy a given session filter.

Declaration

Task<int> ChangeRolesAsync(string filter, ICollection<string> rolesToRemove, ICollection<string> rolesToAdd, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.String	filter	The filter of client sessions for which the change will be applied.
System.Collections.Generic.ICollection<System.String>	rolesToRemove	The collection of roles to be removed from the session.
System.Collections.Generic.ICollection<System.String>	rolesToAdd	The collection of roles to be added to the session.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Int32>	The `Task` representing the current operation.

Remarks

If the task completes successfully, the Task result will be the number of sessions that have matched the filter and for which the specified role changes have been applied.

Initially a session has a set of roles assigned during authentication. A current roles set can be obtained from the $Roles session property.

When a set of session roles changes, its $Roles property changes accordingly. As a role can constrain 'topic' permissions, session subscriptions are re-evaluated based on the new roles set.

The same role must not occur in both rolesToRemove and rolesToAdd sets. Either set can be an empty set but not both.

Exceptions

Type	Condition
System.ArgumentNullException	If `filter`, `rolesToAdd`, or `rolesToRemove` is `null`.
System.ArgumentException	Both `rolesToAdd` and `rolesToRemove` are empty or contain the same role(s).
InvalidFilterException	The `filter` could not be parsed. Thrown by the returned `Task`.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission.
SessionClosedException	The session is closed. Thrown by the returned `Task`.

CloseAsync(ISessionId)

Close a client session.

Declaration

Task<object> CloseAsync(ISessionId clientSessionId)

Parameters

Type	Name	Description
ISessionId	clientSessionId	The client session to close.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The `Task` representing the current operation.

Remarks

If the identified session was closed, the task will complete successfully, and the Task result will be null.

Added in version 6.6.

Exceptions

Type	Condition
System.ArgumentNullException	If `clientSessionId` is `null`.
System.ArgumentException	If `clientSessionId` is an invalid session identifier.
NoSuchSessionException	The identified session was closed before the response was delivered. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

CloseAsync(ISessionId, CancellationToken)

Close a client session.

Declaration

Task<object> CloseAsync(ISessionId clientSessionId, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ISessionId	clientSessionId	The client session to close.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The `Task` representing the current operation.

Remarks

If the identified session was closed, the task will complete successfully, and the Task result will be null.

Added in version 6.6.

Exceptions

Type	Condition
System.ArgumentNullException	If `clientSessionId` is `null`.
System.ArgumentException	If `clientSessionId` is an invalid session identifier.
NoSuchSessionException	The identified session was closed before the response was delivered. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

CloseAsync(String)

Close all client sessions matching a given session filter.

Declaration

Task<int> CloseAsync(string filter)

Parameters

Type	Name	Description
System.String	filter	Filter matches the set of client sessions to close. For details on specifying session filters see ISession.

Returns

Type	Description
System.Threading.Tasks.Task<System.Int32>	The `Task` representing the current operation containing the number of sessions that matched the filter and have been closed.

Remarks

Added in version 6.5.

Exceptions

Type	Condition
System.ArgumentNullException	If `filter` is `null`.
InvalidFilterException	The filter was invalid. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

CloseAsync(String, CancellationToken)

Close all client sessions matching a given session filter.

Declaration

Task<int> CloseAsync(string filter, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.String	filter	Filter matches the set of client sessions to close. For details on specifying session filters see ISession.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Int32>	The `Task` representing the current operation containing the number of sessions that matched the filter and have been closed.

Remarks

Added in version 6.5.

Exceptions

Type	Condition
System.ArgumentNullException	If `filter` is `null`.
InvalidFilterException	The filter was invalid. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

GetSessionLockAsync(String)

Returns details of the session (if any) that holds a named session lock.

Declaration

Task<ISessionLockDetails> GetSessionLockAsync(string lockName)

Parameters

Type	Name	Description
System.String	lockName	The lock name.

Returns

Type	Description
System.Threading.Tasks.Task<ISessionLockDetails>	The `Task` representing the current operation containing the details of the session that currently holds the lock, or null if no session holds the named lock.

Remarks

Added in version 6.12.

Exceptions

Type	Condition
System.ArgumentNullException	If `lockName` is `null`.
SessionSecurityException	The calling session does not have VIEW_SERVER permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

GetSessionLockAsync(String, CancellationToken)

Returns details of the session (if any) that holds a named session lock.

Declaration

Task<ISessionLockDetails> GetSessionLockAsync(string lockName, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.String	lockName	The lock name.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<ISessionLockDetails>	The `Task` representing the current operation containing the details of the session that currently holds the lock, or null if no session holds the named lock.

Remarks

Added in version 6.12.

Exceptions

Type	Condition
System.ArgumentNullException	If `lockName` is `null`.
SessionSecurityException	The calling session does not have VIEW_SERVER permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

GetSessionLocksAsync()

Returns details of all session locks currently held.

Declaration

Task<IReadOnlyDictionary<string, ISessionLockDetails>> GetSessionLocksAsync()

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyDictionary<System.String, ISessionLockDetails>>	The `Task` representing the current operation containing a dictionary of session locks keyed on the lock name where the value identifies the session currently holding the lock. If there are no session locks currently held by anybody this will return an empty dictionary.

Remarks

Added in version 6.12.

Exceptions

Type	Condition
SessionSecurityException	The calling session does not have VIEW_SERVER permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

GetSessionLocksAsync(CancellationToken)

Returns details of all session locks currently held.

Declaration

Task<IReadOnlyDictionary<string, ISessionLockDetails>> GetSessionLocksAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyDictionary<System.String, ISessionLockDetails>>	The `Task` representing the current operation containing a dictionary of session locks keyed on the lock name where the value identifies the session currently holding the lock. If there are no session locks currently held by anybody this will return an empty dictionary.

Remarks

Added in version 6.12.

Exceptions

Type	Condition
SessionSecurityException	The calling session does not have VIEW_SERVER permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

GetSessionPropertiesAsync(ISessionId, List<String>)

Query the server for property values of a specified client session.

Declaration

Task<IReadOnlyDictionary<string, string>> GetSessionPropertiesAsync(ISessionId sessionId, List<string> requiredProperties)

Parameters

Type	Name	Description
ISessionId	sessionId	Identifies the client session.
System.Collections.Generic.List<System.String>	requiredProperties	Specifies the keys of the property values required. See ISession for a list of the available fixed property keys. To request all fixed properties, AllFixedProperties should be included as a key and any other fixed property keys would be ignored. To request all user properties, AllUserProperties should be included as a key and any other user property keys would be ignored. To request no properties supply an empty list.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyDictionary<System.String, System.String>>	A `Task` that completes when a response is received from the server by returning a dictionary of session property values that were requested. If no properties were selected the dictionary will be empty.

Exceptions

Type	Condition
System.ArgumentNullException	The `sessionId` or `requiredProperties` is `null`.
System.ArgumentException	If `sessionId` is an invalid session identifier.
NoSuchSessionException	The identified session was closed before the response was delivered. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION and VIEW_SESSION permissions. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

GetSessionPropertiesAsync(ISessionId, List<String>, CancellationToken)

Query the server for property values of a specified client session.

Declaration

Task<IReadOnlyDictionary<string, string>> GetSessionPropertiesAsync(ISessionId sessionId, List<string> requiredProperties, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ISessionId	sessionId	Identifies the client session.
System.Collections.Generic.List<System.String>	requiredProperties	Specifies the keys of the property values required. See ISession for a list of the available fixed property keys. To request all fixed properties, AllFixedProperties should be included as a key and any other fixed property keys would be ignored. To request all user properties, AllUserProperties should be included as a key and any other user property keys would be ignored. To request no properties supply an empty list.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyDictionary<System.String, System.String>>	A `Task` that completes when a response is received from the server by returning a dictionary of session property values that were requested. If no properties were selected the dictionary will be empty.

Exceptions

Type	Condition
System.ArgumentNullException	The `sessionId` or `requiredProperties` is `null`.
System.ArgumentException	If `sessionId` is an invalid session identifier.
NoSuchSessionException	The identified session was closed before the response was delivered. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION and VIEW_SESSION permissions. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

SessionIdFromString(String)

Restore a ISessionId from a string.

This method allows a ISessionId to be converted to a string with ToString() method and later recovered from the string. This is a client operation. A session that has been closed will not be recreated.

Declaration

[Obsolete("Use Diffusion.SessionIdFromString static method.This method will be removed in a future release.", false)]
ISessionId SessionIdFromString(string sessionIdAsString)

Parameters

Type	Name	Description
System.String	sessionIdAsString	A string previously created with `ToString()` method.

Returns

Type	Description
ISessionId	The ISessionId.

Remarks

Caution

Deprecated since 6.10. Use SessionIdFromString(String) static method. This method will be removed in a future release.

Exceptions

Type	Condition
System.ArgumentNullException	If `sessionIdAsString` is `null`.
System.ArgumentException	If the string is empty or is not compatible with the format as generated by `ToString()`.

SetConflatedAsync(ISessionId, Boolean)

Control client queue conflation.

Declaration

Task<object> SetConflatedAsync(ISessionId clientSessionId, bool conflate)

Parameters

Type	Name	Description
ISessionId	clientSessionId	The client session.
System.Boolean	conflate	true to enable, false to disable.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The `Task` representing the current operation.

Remarks

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 Conflation topic property CONFLATION.

If the conflation policy was updated for the identified session, the task will complete successfully, and the Task result will be null.

Added in version 6.6.

Exceptions

Type	Condition
System.ArgumentNullException	If `clientSessionId` is `null`.
System.ArgumentException	If `clientSessionId` is an invalid session identifier.
NoSuchSessionException	The identified session was closed before the response was delivered. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

SetConflatedAsync(ISessionId, Boolean, CancellationToken)

Control client queue conflation.

Declaration

Task<object> SetConflatedAsync(ISessionId clientSessionId, bool conflate, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ISessionId	clientSessionId	The client session.
System.Boolean	conflate	true to enable, false to disable.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The `Task` representing the current operation.

Remarks

If the conflation policy was updated for the identified session, the task will complete successfully, and the Task result will be null.

Added in version 6.6.

Exceptions

Type	Condition
System.ArgumentNullException	If `clientSessionId` is `null`.
System.ArgumentException	If `clientSessionId` is an invalid session identifier.
NoSuchSessionException	The identified session was closed before the response was delivered. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

SetConflatedAsync(String, Boolean)

Control client queue conflation.

Declaration

Task<int> SetConflatedAsync(string filter, bool conflate)

Parameters

Type	Name	Description
System.String	filter	Identifies the client sessions.
System.Boolean	conflate	true to enable, false to disable.

Returns

Type	Description
System.Threading.Tasks.Task<System.Int32>	The `Task` representing the current operation containing the number of sessions that matched the filter.

Remarks

Added in version 6.5.

Exceptions

Type	Condition
System.ArgumentNullException	If `filter` is `null`.
InvalidFilterException	The filter was invalid. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

SetConflatedAsync(String, Boolean, CancellationToken)

Control client queue conflation.

Declaration

Task<int> SetConflatedAsync(string filter, bool conflate, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.String	filter	Identifies the client sessions.
System.Boolean	conflate	true to enable, false to disable.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Int32>	The `Task` representing the current operation containing the number of sessions that matched the filter.

Remarks

Added in version 6.5.

Exceptions

Type	Condition
System.ArgumentNullException	If `filter` is `null`.
InvalidFilterException	The filter was invalid. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

SetQueueEventHandler(IQueueEventHandler)

Register a handler for client queue threshold events. Each controller session may register a handler. For each event, the server will select a single handler.

Declaration

[Obsolete("Deprecated since 6.12. Use SetQueueEventHandlerAsync(IQueueEventStream) instead.")]
void SetQueueEventHandler(IQueueEventHandler handler)

Parameters

Type	Name	Description
IQueueEventHandler	handler	The queue handler to set.

Remarks

Each control session can register a single handler. See OnActive(IRegisteredHandler) closed (using CloseAsync()) if no longer required. 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 conflating the session.

Caution

Deprecated since 6.12. Use the new SetQueueEventHandlerAsync(IQueueEventStream). This method will be removed in a future release.

Exceptions

Type	Condition
System.ArgumentNullException	If `handler` is `null`.

SetQueueEventHandlerAsync(IQueueEventStream)

Registers a handler for client queue threshold events.

Declaration

Task<IRegistration> SetQueueEventHandlerAsync(IQueueEventStream handler)

Parameters

Type	Name	Description
IQueueEventStream	handler	The queue handler to set.

Returns

Type	Description
System.Threading.Tasks.Task<IRegistration>	A `Task` that completes when the handler has been registered, returning a IRegistration which can be used to unregister the handler.

Remarks

Each control session can register a single handler. When the handler is no longer required, it may be closed using the IRegistration provided by the Task result. 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.

This method is the same as calling SetQueueEventHandlerAsync(IQueueEventStream, CancellationToken) with System.Threading.CancellationToken.None.

Since 6.12.

Exceptions

Type	Condition
System.ArgumentNullException	If `handler` is `null`.
HandlerConflictException	The session has already registered a queue event handler. Thrown by the returned task.
SessionSecurityException	The calling session does not have REGISTER_HANDLER and VIEW_SESSION permissions. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

SetQueueEventHandlerAsync(IQueueEventStream, CancellationToken)

Registers a handler for client queue threshold events.

Declaration

Task<IRegistration> SetQueueEventHandlerAsync(IQueueEventStream handler, CancellationToken cancellationToken)

Parameters

Type	Name	Description
IQueueEventStream	handler	The queue handler to set.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<IRegistration>	A `Task` that completes when the handler has been registered, returning a IRegistration which can be used to unregister the handler.

Remarks

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

This method is the same as calling SetQueueEventHandlerAsync(IQueueEventStream, CancellationToken) with System.Threading.CancellationToken.None.

Since 6.12.

Exceptions

Type	Condition
System.ArgumentNullException	If `handler` is `null`.
HandlerConflictException	The session has already registered a queue event handler. Thrown by the returned task.
SessionSecurityException	The calling session does not have REGISTER_HANDLER and VIEW_SESSION permissions. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

SetSessionPropertiesAsync(ISessionId, Dictionary<String, String>)

Send a request to the server to change the user-defined session properties for a session.

Declaration

Task<IReadOnlyDictionary<string, string>> SetSessionPropertiesAsync(ISessionId sessionId, Dictionary<string, string> properties)

Parameters

Type	Name	Description
ISessionId	sessionId	The session id of the client session.
System.Collections.Generic.Dictionary<System.String, System.String>	properties	The properties to change. Each entry in the dictionary is a property name and the new value. If the value is `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 new properties starting with '$' will be ignored).

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyDictionary<System.String, System.String>>	A `Task` that completes when a response is received from the server by returning a dictionary of session properties that changed.

Remarks

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.

If the session properties were updated, the Task will complete successfully. The result type is a dictionary of properties that changed with their previous values. If no properties were changed, the dictionary will be empty. If any new properties were added, the values in the dictionary will be null to indicate that they do not have an old value.

This method is equivalent to calling SetSessionPropertiesAsync(ISessionId, Dictionary<String, String>, CancellationToken) with System.Threading.CancellationToken.None.

Added in version 6.1.

Exceptions

Type	Condition
System.ArgumentNullException	The `sessionId` or `properties` is `null`.
System.ArgumentException	If `sessionId` is an invalid session identifier.
NoSuchSessionException	The identified session was closed before the response was delivered. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

SetSessionPropertiesAsync(ISessionId, Dictionary<String, String>, CancellationToken)

Send a request to the server to change the user-defined session properties for a session.

Declaration

Task<IReadOnlyDictionary<string, string>> SetSessionPropertiesAsync(ISessionId sessionId, Dictionary<string, string> properties, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ISessionId	sessionId	The session id of the client session.
System.Collections.Generic.Dictionary<System.String, System.String>	properties	The properties to change. Each entry in the dictionary is a property name and the new value. If the value is `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 new properties starting with '$' will be ignored).
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyDictionary<System.String, System.String>>	A `Task` that completes when a response is received from the server by returning a dictionary of session properties that changed.

Remarks

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.

Added in version 6.1.

Exceptions

Type	Condition
System.ArgumentNullException	The `sessionId` or `properties` is `null`.
System.ArgumentException	If `sessionId` is an invalid session identifier.
NoSuchSessionException	The identified session was closed before the response was delivered. Thrown by the returned task.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

SetSessionPropertiesAsync(String, Dictionary<String, String>)

Send a request to the server to set all sessions that satisfy a session filter with the new user-defined session properties.

Declaration

Task<int> SetSessionPropertiesAsync(string filter, Dictionary<string, string> properties)

Parameters

Type	Name	Description
System.String	filter	The session filter.
System.Collections.Generic.Dictionary<System.String, System.String>	properties	The properties to change. Each entry in the dictionary is a property name and the new value. If the value is `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 new properties starting with '$' will be ignored).

Returns

Type	Description
System.Threading.Tasks.Task<System.Int32>	A `Task` that completes when a response is received from the server.

Remarks

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.

If the task completes successfully, the Task result will be null. The result type is Task{Object} rather than Task to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

This method is equivalent to calling SetSessionPropertiesAsync(String, Dictionary<String, String>, CancellationToken) with System.Threading.CancellationToken.None.

Added in version 6.1.

Exceptions

Type	Condition
System.ArgumentNullException	The `filter` or `properties` is `null`.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.
InvalidFilterException	The filter was invalid. Thrown by the returned task.

SetSessionPropertiesAsync(String, Dictionary<String, String>, CancellationToken)

Send a request to the server to set all sessions that satisfy a session filter with the new user-defined session properties.

Declaration

Task<int> SetSessionPropertiesAsync(string filter, Dictionary<string, string> properties, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.String	filter	The session filter.
System.Collections.Generic.Dictionary<System.String, System.String>	properties	The properties to change. Each entry in the dictionary is a property name and the new value. If the value is `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 new properties starting with '$' will be ignored).
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Int32>	A `Task` that completes when a response is received from the server.

Remarks

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.

Added in version 6.1.

Exceptions

Type	Condition
System.ArgumentNullException	The `filter` or `properties` is `null`.
SessionSecurityException	The calling session does not have MODIFY_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.
InvalidFilterException	The filter was invalid. Thrown by the returned task.

SetSessionPropertiesListener(ISessionPropertiesListener, String[])

Registers a listener that will be notified when client sessions are opened, disconnected, reconnected, closed or when selected session property values are updated.

Declaration

[Obsolete("Use the new AddSessionEventListenerAsync, which provides greater functionality and reports on sessions at all cluster members.This method will be removed in a future release.", false)]
void SetSessionPropertiesListener(ISessionPropertiesListener listener, params string[] requiredProperties)

Parameters

Type	Name	Description
ISessionPropertiesListener	listener	The listener to be called with session notifications.
System.String[]	requiredProperties	A list of required property keys. See ISession for a full list of available fixed property keys. To request no properties, null or an empty set may be supplied. To request all fixed properties, AllFixedProperties should be included as a key and any other fixed property keys would be ignored. To request all user properties, AllUserProperties should be included as a key and any other user property keys supplied would be ignored.

Remarks

This only notifies sessions connecting to the same server as the current session and therefore if the Diffusion system is operating as a cluster then the only way to receive notifications for sessions at all cluster members would be to connect separate sessions (and listeners) to each cluster member. When connecting to a cluster it is recommended that the AddSessionEventListenerAsync(ISessionEventStream, ISessionEventParameters) method is used instead.

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 the requiredProperties parameter.

Each control session can register a single listener (See OnRegistered(IRegistration)). A listener may be closed (using CloseAsync()) if no longer required. To set a different listener the current 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 then the listener is not called when session properties are updated.

Caution

Deprecated since 6.11. Use the new AddSessionEventListenerAsync(ISessionEventStream, ISessionEventParameters), which provides greater functionality and reports on sessions at all cluster members. This method will be removed in a future release.

Exceptions

Type	Condition
System.ArgumentNullException	If `listener` is `null`.