Interface IClientControl

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

Assembly: Diffusion.Client.dll

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

public interface IClientControl : IFeature

Inherited Members: IFeature.Session

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, params 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.

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

Parameters

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

Returns

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

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.

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

Parameters

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

Returns

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

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.

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

Parameters

sessionId ISessionId: The client session for which the change will be applied.
rolesToRemove ICollection<string>: The collection of roles to be removed from the session.
rolesToAdd ICollection<string>: The collection of roles to be added to the session.

Returns

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

ArgumentNullException: If sessionId, rolesToAdd, or rolesToRemove is null.
ArgumentException: Both rolesToAdd and rolesToRemove are empty or contain the same role(s).
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.

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

Parameters

sessionId ISessionId: The client session for which the change will be applied.
rolesToRemove ICollection<string>: The collection of roles to be removed from the session.
rolesToAdd ICollection<string>: The collection of roles to be added to the session.
cancellationToken CancellationToken: The cancellation token used to cancel the current operation.

Returns

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

ArgumentNullException: If sessionId, rolesToAdd, or rolesToRemove is null.
ArgumentException: Both rolesToAdd and rolesToRemove are empty or contain the same role(s).
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.

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

Parameters

filter string: The filter of client sessions for which the change will be applied.
rolesToRemove ICollection<string>: The collection of roles to be removed from the session.
rolesToAdd ICollection<string>: The collection of roles to be added to the session.

Returns

Task<int>: 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

ArgumentNullException: If filter, rolesToAdd, or rolesToRemove is null.
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.

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

Parameters

filter string: The filter of client sessions for which the change will be applied.
rolesToRemove ICollection<string>: The collection of roles to be removed from the session.
rolesToAdd ICollection<string>: The collection of roles to be added to the session.
cancellationToken CancellationToken: The cancellation token used to cancel the current operation.

Returns

Task<int>: 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

ArgumentNullException: If filter, rolesToAdd, or rolesToRemove is null.
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.

Task<object> CloseAsync(ISessionId clientSessionId)

Parameters

clientSessionId ISessionId: The client session to close.

Returns

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

ArgumentNullException: If clientSessionId is null.
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.

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

Parameters

clientSessionId ISessionId: The client session to close.
cancellationToken CancellationToken: The cancellation token used to cancel the current operation.

Returns

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

ArgumentNullException: If clientSessionId is null.
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.

Task<int> CloseAsync(string filter)

Parameters

filter string: Filter matches the set of client sessions to close. For details on specifying session filters see ISession.

Returns

Task<int>: 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

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.

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

Parameters

filter string: Filter matches the set of client sessions to close. For details on specifying session filters see ISession.
cancellationToken CancellationToken: The cancellation token used to cancel the current operation.

Returns

Task<int>: 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

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.

Task<ISessionLockDetails> GetSessionLockAsync(string lockName)

Parameters

lockName string: The lock name.

Returns

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

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.

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

Parameters

lockName string: The lock name.
cancellationToken CancellationToken: The cancellation token used to cancel the current operation.

Returns

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

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.

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

Returns

Task<IReadOnlyDictionary<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

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.

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

Parameters

cancellationToken CancellationToken: The cancellation token used to cancel the current operation.

Returns

Task<IReadOnlyDictionary<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

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.

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

Parameters

sessionId ISessionId: Identifies the client session.
requiredProperties List<string>: 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

Task<IReadOnlyDictionary<string, 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

ArgumentNullException: The sessionId or requiredProperties is null.
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.

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

Parameters

sessionId ISessionId: Identifies the client session.
requiredProperties List<string>: 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.
cancellationToken CancellationToken: The cancellation token used to cancel the current operation.

Returns

Task<IReadOnlyDictionary<string, 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

ArgumentNullException: The sessionId or requiredProperties is null.
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.

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

Parameters

sessionIdAsString string: A string previously created with ToString() method.

Returns

ISessionId: The ISessionId.

Remarks

Caution

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

Exceptions

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

SetConflatedAsync(ISessionId, bool)

Control client queue conflation.

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

Parameters

clientSessionId ISessionId: The client session.
conflate bool: true to enable, false to disable.

Returns

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

ArgumentNullException: If clientSessionId is null.
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, bool, CancellationToken)

Control client queue conflation.

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

Parameters

clientSessionId ISessionId: The client session.
conflate bool: true to enable, false to disable.
cancellationToken CancellationToken: The cancellation token used to cancel the current operation.

Returns

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

ArgumentNullException: If clientSessionId is null.
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, bool)

Control client queue conflation.

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

Parameters

filter string: Identifies the client sessions.
conflate bool: true to enable, false to disable.

Returns

Task<int>: The Task representing the current operation containing the number of sessions that matched the filter.

Remarks

Added in version 6.5.

Exceptions

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, bool, CancellationToken)

Control client queue conflation.

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

Parameters

filter string: Identifies the client sessions.
conflate bool: true to enable, false to disable.
cancellationToken CancellationToken: The cancellation token used to cancel the current operation.

Returns

Task<int>: The Task representing the current operation containing the number of sessions that matched the filter.

Remarks

Added in version 6.5.

Exceptions

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.

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

Parameters

handler IQueueEventHandler: 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

ArgumentNullException: If handler is null.

SetQueueEventHandlerAsync(IQueueEventStream)

Registers a handler for client queue threshold events.

Task<IRegistration> SetQueueEventHandlerAsync(IQueueEventStream handler)

Parameters

handler IQueueEventStream: The queue handler to set.

Returns

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

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.

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

Parameters

handler IQueueEventStream: The queue handler to set.
cancellationToken CancellationToken: The cancellation token used to cancel the current operation.

Returns

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

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.

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

Parameters

sessionId ISessionId: The session id of the client session.
properties Dictionary<string, string>: 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

Task<IReadOnlyDictionary<string, 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

ArgumentNullException: The sessionId or properties is null.
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.

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

Parameters

sessionId ISessionId: The session id of the client session.
properties Dictionary<string, string>: 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).
cancellationToken CancellationToken: The cancellation token used to cancel the current operation.

Returns

Task<IReadOnlyDictionary<string, 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

ArgumentNullException: The sessionId or properties is null.
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.

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

Parameters

filter string: The session filter.
properties Dictionary<string, string>: 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

Task<int>: 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

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.

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

Parameters

filter string: The session filter.
properties Dictionary<string, string>: 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).
cancellationToken CancellationToken: The cancellation token used to cancel the current operation.

Returns

Task<int>: 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

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, params string[])

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

[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

listener ISessionPropertiesListener

The listener to be called with session notifications.

requiredProperties string[]

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,
 <xref href="PushTechnology.ClientInterface.Client.Features.Impl.SessionControlConstants.AllFixedProperties" data-throw-if-not-resolved="false"></xref> should be included as a key and any other fixed
 property keys would be ignored.  To request all user properties,
 <xref href="PushTechnology.ClientInterface.Client.Features.Impl.SessionControlConstants.AllUserProperties" data-throw-if-not-resolved="false"></xref> 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

ArgumentNullException: If listener is null.

Table of Contents

Interface IClientControl

Remarks

Access Control

Accessing the feature

Methods

AddSessionEventListenerAsync(ISessionEventStream, ISessionEventParameters)

Parameters

Returns

Remarks

Exceptions

AddSessionEventListenerAsync(ISessionEventStream, ISessionEventParameters, CancellationToken)

Parameters

Returns

Remarks

Exceptions

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

Parameters

Returns

Remarks

Exceptions

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

Parameters

Returns

Remarks

Exceptions

ChangeRolesAsync(string, ICollection<string>, ICollection<string>)

Parameters

Returns

Remarks

Exceptions

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

Parameters

Returns

Remarks

Exceptions

CloseAsync(ISessionId)

Parameters

Returns

Remarks

Exceptions

CloseAsync(ISessionId, CancellationToken)

Parameters

Returns

Remarks

Exceptions

CloseAsync(string)

Parameters

Returns

Remarks

Exceptions

CloseAsync(string, CancellationToken)

Parameters

Returns

Remarks

Exceptions

GetSessionLockAsync(string)

Parameters

Returns

Remarks

Exceptions

GetSessionLockAsync(string, CancellationToken)

Parameters

Returns

Remarks

Exceptions

GetSessionLocksAsync()

Returns

Remarks

Exceptions

GetSessionLocksAsync(CancellationToken)

Parameters

Returns

Remarks

Exceptions

GetSessionPropertiesAsync(ISessionId, List<string>)

Parameters

Returns

Exceptions

GetSessionPropertiesAsync(ISessionId, List<string>, CancellationToken)