Interface IClientControl
This 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 clients (forcibly closing them and so on).
Access Control
A session must have VIEW_SESSION permission to be able to listen for notifications using SetSessionPropertiesListener(ISessionPropertiesListener, String[]) or GetSessionProperties(ISessionId, List<String>, ISessionPropertiesCallback) of other sessions or listen for SetQueueEventHandler(IQueueEventHandler) queue events. In addition REGISTER_HANDLER permission is required to set a session properties listener, a session details listener or queue event handler.
Inherited Members
Namespace: PushTechnology.ClientInterface.Client.Features.Control.Clients
Assembly: Diffusion.Client.dll
Syntax
public interface IClientControl : IFeature
Methods
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. |
ICollection<String> | rolesToRemove | The collection of roles to be removed from the session. |
ICollection<String> | rolesToAdd | The collection of roles to be added to the session. |
Returns
Type | Description |
---|---|
Task<Object> | The |
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 |
---|---|
NoSuchSessionException | There is no session with the given |
SessionSecurityException | The calling session does not have the MODIFY_SESSION and
VIEW_SESSION permissions. Thrown by the returned |
SessionClosedException | The session is closed. Thrown by the returned |
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. |
ICollection<String> | rolesToRemove | The collection of roles to be removed from the session. |
ICollection<String> | rolesToAdd | The collection of roles to be added to the session. |
CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
Type | Description |
---|---|
Task<Object> | The |
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 |
---|---|
NoSuchSessionException | There is no session with the given |
SessionSecurityException | The calling session does not have the MODIFY_SESSION and
VIEW_SESSION permissions. Thrown by the returned |
SessionClosedException | The session is closed. Thrown by the returned |
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 |
---|---|---|
String | filter | The filter of client sessions for which the change will be applied. |
ICollection<String> | rolesToRemove | The collection of roles to be removed from the session. |
ICollection<String> | rolesToAdd | The collection of roles to be added to the session. |
Returns
Type | Description |
---|---|
Task<Int32> | The |
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 |
---|---|
InvalidFilterException | The |
SessionSecurityException | The calling session does not have the MODIFY_SESSION and
VIEW_SESSION permissions. Thrown by the returned |
SessionClosedException | The session is closed. Thrown by the returned |
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 |
---|---|---|
String | filter | The filter of client sessions for which the change will be applied. |
ICollection<String> | rolesToRemove | The collection of roles to be removed from the session. |
ICollection<String> | rolesToAdd | The collection of roles to be added to the session. |
CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
Type | Description |
---|---|
Task<Int32> | The |
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 |
---|---|
InvalidFilterException | The |
SessionSecurityException | The calling session does not have the MODIFY_SESSION and
VIEW_SESSION permissions. Thrown by the returned |
SessionClosedException | The session is closed. Thrown by the returned |
Close(ISessionId, IClientCallback)
Close a client session.
Declaration
void Close(ISessionId clientSessionId, IClientCallback callback)
Parameters
Type | Name | Description |
---|---|---|
ISessionId | clientSessionId | The client session to close. |
IClientCallback | callback | the operation callback. |
Close<TC>(ISessionId, TC, IClientContextCallback<TC>)
Close a client session with a contextual callback.
Declaration
void Close<TC>(ISessionId clientSessionId, TC context, IClientContextCallback<TC> callback)
Parameters
Type | Name | Description |
---|---|---|
ISessionId | clientSessionId | The client session to close. |
TC | context | the context object to pass to the callback. |
IClientContextCallback<TC> | callback | the operation callback. |
Type Parameters
Name | Description |
---|---|
TC |
GetSessionProperties(ISessionId, List<String>, ISessionPropertiesCallback)
Query the server for property values of a specified client session.
Declaration
void GetSessionProperties(ISessionId sessionId, List<string> requiredProperties, ISessionPropertiesCallback callback)
Parameters
Type | Name | Description |
---|---|---|
ISessionId | sessionId | Identifies the client session. |
List<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. |
ISessionPropertiesCallback | callback | Called with the response. |
GetSessionProperties<TC>(ISessionId, List<String>, TC, ISessionPropertiesContextCallback<TC>)
Query the server for property values of a specified client session.
Declaration
void GetSessionProperties<TC>(ISessionId sessionId, List<string> requiredProperties, TC context, ISessionPropertiesContextCallback<TC> callback)
Parameters
Type | Name | Description |
---|---|---|
ISessionId | sessionId | Identifies the client session. |
List<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 may be included as a key in which case any other fixed property keys would be ignored. To request all user properties, AllUserProperties can be included as a key in which case any other user property keys would be ignored. |
TC | context | Passed to the callback to allow requests and responses to be correlated. The caller can use any convenient object reference, including null. |
ISessionPropertiesContextCallback<TC> | callback | Called with the response. |
Type Parameters
Name | Description |
---|---|
TC | The context object type. |
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
ISessionId SessionIdFromString(string sessionIdAsString)
Parameters
Type | Name | Description |
---|---|---|
String | sessionIdAsString | A string previously created with |
Returns
Type | Description |
---|---|
ISessionId | The ISessionId. |
SetConflated(ISessionId, Boolean, IClientCallback)
Control client queue conflation.
Declaration
void SetConflated(ISessionId clientSessionId, bool conflate, IClientCallback callback)
Parameters
Type | Name | Description |
---|---|---|
ISessionId | clientSessionId | The client session. |
Boolean | conflate | true to enable, false to disable. |
IClientCallback | callback | the operation callback |
SetConflated<TC>(ISessionId, Boolean, TC, IClientContextCallback<TC>)
Control client queue conflation with a contextual callback.
Declaration
void SetConflated<TC>(ISessionId clientSessionId, bool conflate, TC context, IClientContextCallback<TC> callback)
Parameters
Type | Name | Description |
---|---|---|
ISessionId | clientSessionId | The client session. |
Boolean | conflate | true to enable, false to disable. |
TC | context | the context to pass to the callback. |
IClientContextCallback<TC> | callback | the operation callback |
Type Parameters
Name | Description |
---|---|
TC |
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.
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 client may choose to act upon client queue events by conflating or throttling the client.
Declaration
void SetQueueEventHandler(IQueueEventHandler handler)
Parameters
Type | Name | Description |
---|---|---|
IQueueEventHandler | handler | the queue handler to set |
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. |
Dictionary<String, String> | properties | The properties to change. Each entry in the dictionary is a
property name and the new value. If the value is |
Returns
Type | Description |
---|---|
Task<IReadOnlyDictionary<String, String>> | A |
Remarks
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
Added in version 6.1.
Exceptions
Type | Condition |
---|---|
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. |
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. |
Dictionary<String, String> | properties | The properties to change. Each entry in the dictionary is a
property name and the new value. If the value is |
CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
Type | Description |
---|---|
Task<IReadOnlyDictionary<String, String>> | A |
Remarks
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.
Added in version 6.1.
Exceptions
Type | Condition |
---|---|
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. |
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<object> SetSessionPropertiesAsync(string filter, Dictionary<string, string> properties)
Parameters
Type | Name | Description |
---|---|---|
String | filter | The session filter. |
Dictionary<String, String> | properties | The properties to change. Each entry in the dictionary is
a property name and the new value. If the value is |
Returns
Type | Description |
---|---|
Task<Object> | A |
Remarks
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
Added in version 6.1.
Exceptions
Type | Condition |
---|---|
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. |
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<object> SetSessionPropertiesAsync(string filter, Dictionary<string, string> properties, CancellationToken cancellationToken)
Parameters
Type | Name | Description |
---|---|---|
String | filter | The session filter. |
Dictionary<String, String> | properties | The properties to change. Each entry in the dictionary is
a property name and the new value. If the value is |
CancellationToken | cancellationToken | The cancellation token used to cancel the current operation. |
Returns
Type | Description |
---|---|
Task<Object> | A |
Remarks
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.
Added in version 6.1.
Exceptions
Type | Condition |
---|---|
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. |
SetSessionPropertiesListener(ISessionPropertiesListener, String[])
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 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.
Declaration
void SetSessionPropertiesListener(ISessionPropertiesListener listener, params string[] requiredProperties)
Parameters
Type | Name | Description |
---|---|---|
ISessionPropertiesListener | listener | The listener to be called with session notifications. |
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 requested 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. |
SetThrottled(ISessionId, ThrottlerType, Int32, IClientCallback)
Instruct a client to throttle the queue according to the provided parameters.
Declaration
void SetThrottled(ISessionId clientSessionId, ThrottlerType throttlerType, int throttlingLimit, IClientCallback callback)
Parameters
Type | Name | Description |
---|---|---|
ISessionId | clientSessionId | The client session. |
ThrottlerType | throttlerType | The type of throttling. |
Int32 | throttlingLimit | The throttling limit. The meaning of this limit depends on the throttler type. |
IClientCallback | callback | the operation callback |
Remarks
DEPRECATED: Per-session throttling has been deprecated in favor of the new per-topic throttling capabilities provided by ITopicViews. This method will be removed in a future release.
SetThrottled<TC>(ISessionId, ThrottlerType, Int32, TC, IClientContextCallback<TC>)
Instruct a client to throttle the queue according to the provided parameters.
Declaration
void SetThrottled<TC>(ISessionId clientSessionId, ThrottlerType throttlerType, int throttlingLimit, TC context, IClientContextCallback<TC> callback)
Parameters
Type | Name | Description |
---|---|---|
ISessionId | clientSessionId | The client session. |
ThrottlerType | throttlerType | The type of throttling. |
Int32 | throttlingLimit | The throttling limit. The meaning of this limit depends on the throttler type. |
TC | context | the context to pass to the callback. |
IClientContextCallback<TC> | callback | the operation callback |
Type Parameters
Name | Description |
---|---|
TC |
Remarks
DEPRECATED: Per-session throttling has been deprecated in favor of the new per-topic throttling capabilities provided by ITopicViews. This method will be removed in a future release.