Interface IMessagingControl
This feature provides a client session with the ability to use messaging functionality to communicate directly with other client sessions.
Namespace: PushTechnology.ClientInterface.Client.Features.Control.Topics
Assembly: Diffusion.Client.dll
Syntax
public interface IMessagingControl : IFeature, ISendOptionsBuilderFactory
Remarks
This feature allows the registration of request handlers to receive messages, and the sending of requests to individual sessions or selections of sessions.
Message requests are sent and received for a particular path. The message path provides a hierarchical context for the recipient.
Message 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 messages with topics, or an arbitrary path can be chosen.
A message 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 message path - an error is returned to the sending session in this case.
Handlers for receiving messages are registered for a path. Each session may register at most one handler for a given path. When dispatching a message, 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 message from a client session. The current values of the named properties for the originating session will be delivered with the message.
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.
Request-Response Messaging
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.
One-way Messaging (deprecated)
This feature can also be used to send one-way messages to other clients. The sender will be notified that the messages have been delivered, but no response is possible. It is also possible to register message handlers to receive one-way messages sent from other clients.
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
AddMessageHandler(String, IMessageHandler, String[])
Registers a message handler to handle messages received from other client sessions for a branch of the topic tree.
Declaration
void AddMessageHandler(string topicPath, IMessageHandler handler, params string[] sessionProperties)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The topic path. |
IMessageHandler | handler | The handler for all messages sent on topics beneath the specified branch (unless overridden by a handler registered against a more specific branch) |
String[] | sessionProperties | The list of required property keys. See ISession for a full list of available fixed property keys. To request no properties, supply an empty list. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. See SendRequestAsync<TRequest, TResponse>(ISessionId, String, TRequest) and SendRequestToFilterAsync<TRequest, TResponse>(String, String, TRequest, IFilteredRequestCallback<TResponse>). This method will be removed in a future release.
The handler will be invoked for topics below the specified path to which messages have been sent. This will only receive messages sent from a client (for example by one of the send methods in the ITopics feature) and not any topic updates.
Each control session may register a single handler for a branch (See
OnActive(String, IRegisteredHandler)).
When the handler is no longer required, it may be closed using
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 |
Type Parameters
Name | Description |
---|---|
TRequest | The type of the request. If this class is not supported by the available data types, an
|
TResponse | The type of the response. If this class is not supported by the available data types, an
|
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
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 |
SessionSecurityException | The session does not have |
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
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 |
Type Parameters
Name | Description |
---|---|
TRequest | The type of the request. If this class is not supported by the available data types, an
|
TResponse | The type of the response. If this class is not supported by the available data types, an
|
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 |
SessionSecurityException | The session does not have |
Send(ISessionId, String, IBytes, ISendCallback)
Sends a message to a session through a specific topic.
Declaration
void Send(ISessionId sessionId, string topicPath, IBytes message, ISendCallback callback)
Parameters
Type | Name | Description |
---|---|---|
ISessionId | sessionId | The session to send the message to. |
String | topicPath | The topic path the message is associated with. |
IBytes | message | The message to send. This can be any subtype of IBytes, for example IBinary or IJSON. |
ISendCallback | callback | The callback to receive operation status notifications. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SendRequestAsync<TRequest, TResponse>(ISessionId, String, TRequest) instead. This method will be removed in a future release.
This is equivalent to calling Send(ISessionId, String, IBytes, ITopicSendOptions, ISendCallback) with default options.
Send(ISessionId, String, IBytes, ITopicSendOptions, ISendCallback)
Sends a message to a session through a specific topic.
Declaration
void Send(ISessionId sessionId, string topicPath, IBytes message, ITopicSendOptions options, ISendCallback callback)
Parameters
Type | Name | Description |
---|---|---|
ISessionId | sessionId | The session to send the message to. |
String | topicPath | The topic path the message is associated with. |
IBytes | message | The message to send. This can be any subtype of IBytes, for example IContent, IBinary or IJSON. |
ITopicSendOptions | options | The message options, including headers and priority. |
ISendCallback | callback | The callback to receive operation status notifications. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SendRequestAsync<TRequest, TResponse>(ISessionId, String, TRequest) instead. This method will be removed in a future release.
Send(ISessionId, String, String, ISendCallback)
Sends a message to a session through a specific topic.
Declaration
void Send(ISessionId sessionId, string topicPath, string message, ISendCallback callback)
Parameters
Type | Name | Description |
---|---|---|
ISessionId | sessionId | The session to send the message to. |
String | topicPath | The topic path the message is associated with. |
String | message | The message to send. |
ISendCallback | callback | The callback to receive operation status notifications. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SendRequestAsync<TRequest, TResponse>(ISessionId, String, TRequest) instead. This method will be removed in a future release.
This is equivalent to calling Send(ISessionId, String, IBytes, ISendCallback) with string content.
Since 5.3
Send<TContext>(ISessionId, String, IBytes, TContext, ISendContextCallback<TContext>)
Sends message to a session through a specific topic.
Declaration
void Send<TContext>(ISessionId sessionId, string topicPath, IBytes message, TContext context, ISendContextCallback<TContext> callback)
Parameters
Type | Name | Description |
---|---|---|
ISessionId | sessionId | The session to send the message to. |
String | topicPath | The topic path the message is associated with. |
IBytes | message | The message to send. This can be any subtype of IBytes, for example IBinary or IJSON. |
TContext | context | The context to pass to the callback. This may be null. |
ISendContextCallback<TContext> | callback | The callback to receive operation status notifications. |
Type Parameters
Name | Description |
---|---|
TContext | The context type. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SendRequestAsync<TRequest, TResponse>(ISessionId, String, TRequest) instead. This method will be removed in a future release.
This is equivalent to calling Send<TContext>(ISessionId, String, IBytes, ITopicSendOptions, TContext, ISendContextCallback<TContext>) with default options.
Send<TContext>(ISessionId, String, IBytes, ITopicSendOptions, TContext, ISendContextCallback<TContext>)
Sends message to a session through a specific topic.
Declaration
void Send<TContext>(ISessionId sessionId, string topicPath, IBytes message, ITopicSendOptions options, TContext context, ISendContextCallback<TContext> callback)
Parameters
Type | Name | Description |
---|---|---|
ISessionId | sessionId | The session to send the message to. |
String | topicPath | The topic path the message is associated with. |
IBytes | message | The message to send. This can be any subtype of IBytes, for example IBinary or IJSON. |
ITopicSendOptions | options | The message options, including headers and priority. |
TContext | context | The context to pass to the callback. This may be null. |
ISendContextCallback<TContext> | callback | The callback to receive operation status notifications. |
Type Parameters
Name | Description |
---|---|
TContext | The context type. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SendRequestAsync<TRequest, TResponse>(ISessionId, String, TRequest) instead. This method will be removed in a future release.
Send<TContext>(ISessionId, String, String, TContext, ISendContextCallback<TContext>)
Sends message to a session through a specific topic.
Declaration
void Send<TContext>(ISessionId sessionId, string topicPath, string message, TContext context, ISendContextCallback<TContext> callback)
Parameters
Type | Name | Description |
---|---|---|
ISessionId | sessionId | The session to send the message to. |
String | topicPath | The topic path the message is associated with. |
String | message | The message to send. |
TContext | context | The context to pass to the callback. This may be null. |
ISendContextCallback<TContext> | callback | The callback to receive operation status notifications. |
Type Parameters
Name | Description |
---|---|
TContext | The context type. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SendRequestAsync<TRequest, TResponse>(ISessionId, String, TRequest) instead. This method will be removed in a future release.
This is equivalent to calling Send<TContext>(ISessionId, String, IBytes, TContext, ISendContextCallback<TContext>) with string content.
Since 5.3
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 |
Type Parameters
Name | Description |
---|---|
TRequest | The type of the request. |
TResponse | The type of the response. |
Remarks
If the TResponse
. Otherwise, the
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 |
Returns
Type | Description |
---|---|
Task<TResponse> | A |
Type Parameters
Name | Description |
---|---|
TRequest | The type of the request. |
TResponse | The type of the response. |
Remarks
If the TResponse
. Otherwise, the
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 |
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
Exceptions
Type | Condition |
---|---|
InvalidFilterException | The |
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 |
Returns
Type | Description |
---|---|
Task<Int32> | A |
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
Exceptions
Type | Condition |
---|---|
InvalidFilterException | The |
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. |
SendToFilter(String, String, IBytes, ISendToFilterCallback)
Sends a message to all sessions that satisfy a given session filter.
Declaration
void SendToFilter(string filter, string topicPath, IBytes message, ISendToFilterCallback callback)
Parameters
Type | Name | Description |
---|---|---|
String | filter | The session filter expression. |
String | topicPath | The topic path the message is associated with. |
IBytes | message | The message to send. This can be any subtype of IBytes, for example IBinary or IJSON. |
ISendToFilterCallback | callback | The callback to receive operation status notifications. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SendRequestToFilterAsync<TRequest, TResponse>(String, String, TRequest, IFilteredRequestCallback<TResponse>) instead. This method will be removed in a future release.
This is equivalent to calling SendToFilter(String, String, IBytes, ITopicSendOptions, ISendToFilterCallback) with default options.
Since 5.5
SendToFilter(String, String, IBytes, ITopicSendOptions, ISendToFilterCallback)
Sends a message to all sessions that satisfy a given session filter.
Declaration
void SendToFilter(string filter, string topicPath, IBytes message, ITopicSendOptions options, ISendToFilterCallback callback)
Parameters
Type | Name | Description |
---|---|---|
String | filter | The session filter expression. |
String | topicPath | The topic path the message is associated with. |
IBytes | message | The message to send. This can be any subtype of IBytes, for example IBinary or IJSON. |
ITopicSendOptions | options | The message options, including headers and priority. |
ISendToFilterCallback | callback | The callback to receive operation status notifications. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SendRequestToFilterAsync<TRequest, TResponse>(String, String, TRequest, IFilteredRequestCallback<TResponse>) instead. This method will be removed in a future release.
Since 5.5
SendToFilter(String, String, String, ISendToFilterCallback)
Sends a message to all sessions that satisfy a given session filter.
Declaration
void SendToFilter(string filter, string topicPath, string message, ISendToFilterCallback callback)
Parameters
Type | Name | Description |
---|---|---|
String | filter | The session filter expression. |
String | topicPath | The topic path the message is associated with. |
String | message | The message to send. |
ISendToFilterCallback | callback | The callback to receive operation status notifications. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SendRequestToFilterAsync<TRequest, TResponse>(String, String, TRequest, IFilteredRequestCallback<TResponse>) instead. This method will be removed in a future release.
This is equivalent to calling SendToFilter(String, String, IBytes, ISendToFilterCallback) with string content.
Since 5.5
SendToFilter<TContext>(String, String, IBytes, TContext, ISendToFilterContextCallback<TContext>)
Sends a message to all sessions that satisfy a given session filter.
Declaration
void SendToFilter<TContext>(string filter, string topicPath, IBytes message, TContext context, ISendToFilterContextCallback<TContext> callback)
Parameters
Type | Name | Description |
---|---|---|
String | filter | The session filter expression. |
String | topicPath | The topic path the message is associated with. |
IBytes | message | The message to send. This can be any subtype of IBytes, for example IBinary or IJSON. |
TContext | context | The context to pass to the callback. This may be null. |
ISendToFilterContextCallback<TContext> | callback | The callback to receive operation status notifications. |
Type Parameters
Name | Description |
---|---|
TContext | The context type. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SendRequestToFilterAsync<TRequest, TResponse>(String, String, TRequest, IFilteredRequestCallback<TResponse>) instead. This method will be removed in a future release.
This is equivalent to calling SendToFilter<TContext>(String, String, IBytes, ITopicSendOptions, TContext, ISendToFilterContextCallback<TContext>) with default options.
Since 5.5
SendToFilter<TContext>(String, String, IBytes, ITopicSendOptions, TContext, ISendToFilterContextCallback<TContext>)
Sends a message to all sessions that satisfy a given session filter.
Declaration
void SendToFilter<TContext>(string filter, string topicPath, IBytes message, ITopicSendOptions options, TContext context, ISendToFilterContextCallback<TContext> callback)
Parameters
Type | Name | Description |
---|---|---|
String | filter | The session filter expression. |
String | topicPath | The topic path the message is associated with. |
IBytes | message | The message to send. This can be any subtype of IBytes, for example IBinary or IJSON. |
ITopicSendOptions | options | The message options, including headers and priority. |
TContext | context | The context to pass to the callback. This may be null. |
ISendToFilterContextCallback<TContext> | callback | The callback to receive operation status notifications. |
Type Parameters
Name | Description |
---|---|
TContext | The context type. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SendRequestToFilterAsync<TRequest, TResponse>(String, String, TRequest, IFilteredRequestCallback<TResponse>) instead. This method will be removed in a future release.
Since 5.5
SendToFilter<TContext>(String, String, String, TContext, ISendToFilterContextCallback<TContext>)
Sends a message to all sessions that satisfy a given session filter.
Declaration
void SendToFilter<TContext>(string filter, string topicPath, string message, TContext context, ISendToFilterContextCallback<TContext> callback)
Parameters
Type | Name | Description |
---|---|---|
String | filter | The session filter expression. |
String | topicPath | The topic path the message is associated with. |
String | message | The message to send. |
TContext | context | The context to pass to the callback. This may be null. |
ISendToFilterContextCallback<TContext> | callback | The callback to receive operation status notifications. |
Type Parameters
Name | Description |
---|---|
TContext | The context type. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SendRequestToFilterAsync<TRequest, TResponse>(String, String, TRequest, IFilteredRequestCallback<TResponse>) instead. This method will be removed in a future release.
This is equivalent to calling SendToFilter<TContext>(String, String, IBytes, TContext, ISendToFilterContextCallback<TContext>) with string content.
Since 5.5