Interface IMessagingControl

This feature provides a client session with the ability to use request-response messaging to communicate directly with other client sessions.

Inherited Members

IMessaging.SendRequestAsync<TRequest, TResponse>(String, TRequest, CancellationToken)

IMessaging.SendRequestAsync<TRequest, TResponse>(String, TRequest)

IMessaging.SetRequestStream<TRequest, TResponse>(String, IRequestStream<TRequest, TResponse>)

IMessaging.RemoveRequestStream(String)

IFeature.Session

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

Assembly: Diffusion.Client.dll

Syntax

public interface IMessagingControl : IMessaging, IFeature

Remarks

Deprecated: The IMessagingControl feature has been obsoleted by the IMessaging feature and will be removed in a future release. The IMessaging feature provides equivalent and additional functionality.

This feature allows the registration of request handlers to receive requests, and the sending of requests to individual sessions or selections of sessions.

Requests are sent and received for a particular path. The path provides a hierarchical context for the recipient.

Request paths are distinct from topic paths. A topic with the path need not exist on the server; if a topic does exist, it is unaffected by messaging. An application can use the same path to associate requests with topics, or an arbitrary path can be chosen.

A request sent directly to another session is discarded if the receiving session is no longer connected or does not have a stream that matches the request path – an error is returned to the sending session in this case.

Handlers for receiving requests are registered for a path. Each session may register at most one handler for a given path. When dispatching a request, the server will consider all registered handlers and select one registered for the most specific path. If multiple sessions have registered a handler registered for a path, one will be chosen arbitrarily.

When registering handlers to receive messages it is also possible to indicate that certain session properties (see ISession for a full description of session properties), should be delivered with each request from a client session. The current values of the named properties for the originating session will be delivered with the request.

Messages can also be sent using 'filters', (see ISession for a full description of session filters), where the message is delivered to all sessions that satisfy a particular filter expression.

Typed request-response messaging allows applications to send requests (of type TRequest) and receive responses (of type TResponse) in the form of a Task. Using this feature, applications send requests to specific sessions using SendRequestAsync<TRequest, TResponse>(ISessionId, String, TRequest). Applications receiving requests from a specific session must have a registered handler at the server, using AddRequestHandlerAsync<TRequest, TResponse>(String, IRequestHandler<TRequest, TResponse>, String[]). When a request is received, the OnRequest(TRequest, IRequestContext, IResponder<TResponse>) method is triggered, to which a response can be sent using the provided Respond(TResponse) method call.

---

Access Control

The message path is also used for access control. Authorization to send messages associated with a message path can be controlled using path-scoped permissions. This allows security roles to be granted to entire branches of the path hierarchy.

Sending a request/message to a specific session requires SEND_TO_SESSION permission. To add a request/message handler, the control client session must have REGISTER_HANDLER permissions and if registering to receive session property values, the session must also have VIEW_SESSION permissions.

Methods

AddRequestHandlerAsync<TRequest, TResponse>(String, IRequestHandler<TRequest, TResponse>, CancellationToken, String[])

Registers a IRequestHandler<TRequest, TResponse> that will handle requests from other client sessions for a branch of the message path hierarchy.

Declaration

Task<IRegistration> AddRequestHandlerAsync<TRequest, TResponse>(string path, IRequestHandler<TRequest, TResponse> handler, CancellationToken cancellationToken, params string[] sessionProperties)

Parameters

Type	Name	Description
String	path	The request message path.
IRequestHandler<TRequest, TResponse>	handler	Request handler to be registered at the server.
CancellationToken	cancellationToken
String[]	sessionProperties	A list of keys of session properties that should be supplied with each request. See The cancellation token used to cancel the current operation. ISession for a full list of available fixed property keys. To request no properties, supply an empty list. To request all fixed properties, include AllFixedProperties as a key. In this case, any other fixed property keys are ignored. To request all user properties, include AllUserProperties as a key. In this case, any other user properties are ignored.

Returns

Type	Description
Task<IRegistration>	A that completes when the handler has been registered, returning a IRegistration which can be used to unregister the handler. Otherwise, the will complete with an exception.

Type Parameters

Name	Description
TRequest	The type of the request. If this class is not supported by the available data types, an will be thrown.
TResponse	The type of the response. If this class is not supported by the available data types, an will be thrown.

Remarks

Each control session may register a single handler for a branch. When the handler is no longer required, it may be closed using the CloseAsync() provided by the result. To change the handler for a particular branch, the previous handler must first be closed.

Since 6.1

Exceptions

Type	Condition
SessionClosedException	The session is closed. Thrown by the returned task.
HandlerConflictException	The session has already registered a handler for this message path. Thrown by the returned task.
SessionSecurityException	The session does not have REGISTER_HANDLER permission to register a request handler on the server. Thrown by the returned task.
SessionSecurityException	The session does not have VIEW_SESSION permission to access the client's session properties. Thrown by the returned task.

AddRequestHandlerAsync<TRequest, TResponse>(String, IRequestHandler<TRequest, TResponse>, String[])

Registers a request handler to handle requests from other client sessions for a branch of the message path hierarchy.

Each control session may register a single handler for a branch. When the handler is no longer required, it may be closed using the CloseAsync() provided by the result. To change the handler for a particular branch the previous handler must first be closed.

Declaration

Task<IRegistration> AddRequestHandlerAsync<TRequest, TResponse>(string path, IRequestHandler<TRequest, TResponse> handler, params string[] sessionProperties)

Parameters

Type	Name	Description
String	path	The request message path.
IRequestHandler<TRequest, TResponse>	handler	Request handler to be registered at the server.
String[]	sessionProperties	A list of keys of session properties that should be supplied with each request. See ISession for a full list of available fixed property keys. To request no properties, supply an empty list. To request all fixed properties, include AllFixedProperties as a key. In this case, any other fixed property keys would be ignored. To request all user properties, include AllUserProperties as a key. In this case, any other user properties are ignored.

Returns

Type	Description
Task<IRegistration>	A that completes when the handler has been registered, returning a IRegistration which can be used to unregister the handler. Otherwise, the will complete with an exception.

Type Parameters

Name	Description
TRequest	The type of the request. If this class is not supported by the available data types, an will be thrown.
TResponse	The type of the response. If this class is not supported by the available data types, an will be thrown.

Remarks

Since 6.1

Exceptions

Type	Condition
SessionClosedException	The session is closed. Thrown by the returned task.
HandlerConflictException	The session has already registered a handler for this message path. Thrown by the returned task.
SessionSecurityException	The session does not have REGISTER_HANDLER permission to register a request handler on the server. Thrown by the returned task.
SessionSecurityException	The session does not have VIEW_SESSION permission to access the client's session properties. Thrown by the returned task.

SendRequestAsync<TRequest, TResponse>(ISessionId, String, TRequest)

Sends a request.

Declaration

Task<TResponse> SendRequestAsync<TRequest, TResponse>(ISessionId sessionId, string path, TRequest request)

Parameters

Type	Name	Description
ISessionId	sessionId	The session identifier.
String	path	The path to send a request to.
TRequest	request	The request to send.

Returns

Type	Description
Task<TResponse>	A that completes when a response has been received by a handler.

Type Parameters

Name	Description
TRequest	The type of the request.
TResponse	The type of the response.

Remarks

If the completes successfully, its result will be the response (to the request) of type TResponse. Otherwise, the will complete with an exception.

Since 6.1

Exceptions

Type	Condition
UnhandledMessageException	There is no handler registered on the server to receive requests for this message path. Thrown by the returned task.
IncompatibleDatatypeException	The request is not compatible with the data type bound to the handler's message path. Thrown by the returned task.
RejectedRequestException	The request has been rejected by the recipient session calling Reject(String). Thrown by the returned task.
SessionClosedException	The session is closed. Thrown by the returned task.
SessionSecurityException	The session does not have SEND_TO_MESSAGE_HANDLER permission. Thrown by the returned task.

SendRequestAsync<TRequest, TResponse>(ISessionId, String, TRequest, CancellationToken)

Sends a request.

Declaration

Task<TResponse> SendRequestAsync<TRequest, TResponse>(ISessionId sessionId, string path, TRequest request, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ISessionId	sessionId	The session identifier.
String	path	The path to send a request to.
TRequest	request	The request to send.
CancellationToken	cancellationToken	The for the created.

Returns

Type	Description
Task<TResponse>	A that completes when a response has been received by a handler.

Type Parameters

Name	Description
TRequest	The type of the request.
TResponse	The type of the response.

Remarks

If the completes successfully, its result will be the response (to the request) of type TResponse. Otherwise, the will complete with an exception.

Since 6.1

Exceptions

Type	Condition
UnhandledMessageException	There is no handler registered on the server to receive requests for this message path. Thrown by the returned task.
IncompatibleDatatypeException	The request is not compatible with the data type bound to the handler's message path. Thrown by the returned task.
RejectedRequestException	The request has been rejected by the recipient session calling Reject(String). Thrown by the returned task.
SessionClosedException	The session is closed. Thrown by the returned task.
SessionSecurityException	The session does not have SEND_TO_MESSAGE_HANDLER permission. Thrown by the returned task.

SendRequestToFilterAsync<TRequest, TResponse>(String, String, TRequest, IFilteredRequestCallback<TResponse>)

Sends a request to all sessions that satisfy a given session filter.

Declaration

Task<int> SendRequestToFilterAsync<TRequest, TResponse>(string filter, string path, TRequest request, IFilteredRequestCallback<TResponse> callback)

Parameters

Type	Name	Description
String	filter	The session filter expression.
String	path	Message path used by the recipient to select an appropriate handler.
TRequest	request	The request object.
IFilteredRequestCallback<TResponse>	callback	The callback to receive notification of responses (or errors) from sessions.

Returns

Type	Description
Task<Int32>	A that completes when the server has dispatched all the requests.

Type Parameters

Name	Description
TRequest	The request type.
TResponse	The response type.

Remarks

Since 6.1

If the server has successfully evaluated the filter, the result contains the number of sessions the request was sent to. Failure to send a request to a particular matching session is reported to the callback. Otherwise, the will complete with an exception.

Exceptions

Type	Condition
InvalidFilterException	The filter parameter could not be parsed. Thrown by the returned task.
SessionSecurityException	The calling session does not have SEND_TO_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

SendRequestToFilterAsync<TRequest, TResponse>(String, String, TRequest, IFilteredRequestCallback<TResponse>, CancellationToken)

Sends a request to all sessions that satisfy a given session filter.

Declaration

Task<int> SendRequestToFilterAsync<TRequest, TResponse>(string filter, string path, TRequest request, IFilteredRequestCallback<TResponse> callback, CancellationToken cancellationToken)

Parameters

Type	Name	Description
String	filter	The session filter expression.
String	path	Message path used by the recipient to select an appropriate handler.
TRequest	request	The request object.
IFilteredRequestCallback<TResponse>	callback	The callback to receive notification of responses (or errors) from sessions.
CancellationToken	cancellationToken	The cancellation token for the returned.

Returns

Type	Description
Task<Int32>	A that completes when the server has dispatched all the requests.

Type Parameters

Name	Description
TRequest	The request type.
TResponse	The response type.

Remarks

Since 6.1

If the server has successfully evaluated the filter, the result contains the number of sessions the request was sent to. Failure to send a request to a particular matching session is reported to the callback. Otherwise, the will complete with an exception.

Exceptions

Type	Condition
InvalidFilterException	The filter parameter could not be parsed. Thrown by the returned task.
SessionSecurityException	The calling session does not have SEND_TO_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.