Interface IMessaging
The feature that provides a client session with messaging capabilities.
Namespace: PushTechnology.ClientInterface.Client.Features
Assembly: Diffusion.Client.dll
Syntax
public interface IMessaging : IFeature, ISendOptionsBuilderFactory
Remarks
Each message is delivered to a request stream registered with the server. Additionally, the server and other clients (through IMessagingControl can send messages to be received using this feature.
Messaging is distinct from the publish/subscribe ITopics feature which provides streams of topic updates.
Messages 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.
Messages from other clients are received via IStream. Streams receive an OnClose() callback when unregistered and an OnError(ErrorReason) callback if the session is closed.
Request-Response Messaging
Typed request-response messaging allows applications to send requests (of type TRequest
) and receive
responses (of type TRequest
) in the form of a Task
. Using Messaging, applications send requests
to paths using SendRequestAsync<TRequest, TResponse>(String, TRequest). In order to
receive requests, applications must have a local request stream assigned to the specific path, using
SetRequestStream<TRequest, TResponse>(String, IRequestStream<TRequest, TResponse>).
When a request is received, the
OnRequest(String, TRequest, IResponder<TResponse>) method on
the stream is triggered, to which a response can be sent using the provided
Respond(TResponse) method call.
One-way Messaging (deprecated)
One-way messaging allows a client to send an untyped message to be sent to a path and be notified that the message has been delivered. No response is possible.
A client can listen for one-way messages for a selection of paths by adding (with AddMessageStream(String, IMessageStream)) one or more IMessageStream implementations. The mapping of selectors to message streams is maintained locally in the client process. Any number of message streams for inbound messages can be added on various selectors. If a message is received on a message path that matches with no message streams, it is passed to any message streams that have been registered with AddFallbackMessageStream(IMessageStream).
Access Control
A client session needs SEND_TO_MESSAGE_HANDLER permission for the message paths to which it sends messages. If a client sends messages to a message path for which it does not have permission, the message is discarded by the server.
Methods
AddFallbackMessageStream(IMessageStream)
Adds a fallback message stream.
Declaration
void AddFallbackMessageStream(IMessageStream stream)
Parameters
Type | Name | Description |
---|---|---|
IMessageStream | stream | The message stream to add as a fallback stream. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SetRequestStream<TRequest, TResponse>(String, IRequestStream<TRequest, TResponse>) instead. This method will be removed in a future release.
When a message is received from the server, it will be passed on to all message streams that have been AddMessageStream(ITopicSelector, IMessageStream) with matching selectors. If no message stream is registered with a matching selector, the fallback message streams that have been registered using this method will be called instead.
Zero, one, or many fallback message streams can be set. If there is no fallback message stream, messages that match no other IMessageStream will be discarded.
Adding the same message stream (as determined by equals more than once has no effect.
Since 5.1
AddMessageStream(ITopicSelector, IMessageStream)
Adds a message stream for messages received from the server on topics that match a given ITopicSelector.
Declaration
void AddMessageStream(ITopicSelector topics, IMessageStream stream)
Parameters
Type | Name | Description |
---|---|---|
ITopicSelector | topics | The selector of one or more topics. |
IMessageStream | stream | The stream to add. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SetRequestStream<TRequest, TResponse>(String, IRequestStream<TRequest, TResponse>) instead. This method will be removed in a future release.
A message stream may be registered against any number of selectors.
When a message is received, it will be passed to each message stream that matches the message's topic path. If there is no matching topic stream, the AddFallbackMessageStream(IMessageStream) will be called instead.
Since 5.1
AddMessageStream(String, IMessageStream)
Adds a message stream for messages received from the server on topics that match the given topic selector expression.
Declaration
void AddMessageStream(string topics, IMessageStream stream)
Parameters
Type | Name | Description |
---|---|---|
String | topics | The topics as a topic selector expression. |
IMessageStream | stream | The stream to add. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use SetRequestStream<TRequest, TResponse>(String, IRequestStream<TRequest, TResponse>) instead. This method will be removed in a future release.
This is equivalent to calling AddMessageStream(ITopicSelector, IMessageStream) with a selector parsed from the given string expression.
Since 5.1
Exceptions
Type | Condition |
---|---|
TopicSelectorFormatException | The |
RemoveMessageStream(IMessageStream)
Removes a message stream.
Declaration
void RemoveMessageStream(IMessageStream stream)
Parameters
Type | Name | Description |
---|---|---|
IMessageStream | stream | The message stream to remove. |
Remarks
Deprecated: One-way messaging is deprecated in favor of request-response messaging. Use RemoveRequestStream(String) instead. This method will be removed in a future release.
More formally, this method removes all message streams that compare equal to stream, regardless of the topic selector for which they are registered. It will also remove any fallback stream equal to stream. If there are no such message streams, no changes are made.
Since 5.1
RemoveRequestStream(String)
Removes the request stream at a particular path.
Declaration
IStream RemoveRequestStream(string path)
Parameters
Type | Name | Description |
---|---|---|
String | path | The path at which to remove the request stream. |
Returns
Type | Description |
---|---|
IStream | The request stream that was removed from the path. If the path does not have a request stream assigned (or
the path does not exist), |
Remarks
Since 6.1
Send(String, IBytes, ISendCallback)
Sends a message.
Declaration
void Send(string topicPath, IBytes message, ISendCallback callback)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The topic path to send the message to. |
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>(String, TRequest) instead. This method will be removed in a future release.
This is equivalent to calling Send(String, IBytes, ITopicSendOptions, ISendCallback) with no send options.
Send(String, IBytes, ITopicSendOptions, ISendCallback)
Sends a message.
Declaration
void Send(string topicPath, IBytes message, ITopicSendOptions options, ISendCallback callback)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The topic path to send the message to. |
IBytes | message | The message to send. This can be any subtype of IBytes, for example IBinary or IJSON. |
ITopicSendOptions | options | The options for sending the given message. |
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>(String, TRequest) instead. This method will be removed in a future release.
Send(String, String, ISendCallback)
Sends a message.
Declaration
void Send(string topicPath, string message, ISendCallback callback)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The topic path to send the message to. |
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>(String, TRequest) instead. This method will be removed in a future release.
This is equivalent to calling Send(String, IBytes, ITopicSendOptions, ISendCallback) with string content and no send options.
Since 5.3
Send<TContext>(String, IBytes, TContext, ISendContextCallback<TContext>)
Sends a message.
Declaration
void Send<TContext>(string topicPath, IBytes message, TContext context, ISendContextCallback<TContext> callback)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The topic path to send the message to. |
IBytes | message | The message to send. This can be any subtype of IBytes, for example IBinary or IJSON. |
TContext | context | The context passed to the callback with the reply to allow requests and replies to be correlated. The caller may use any convenient object reference, including 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>(String, TRequest) instead. This method will be removed in a future release.
This is equivalent to calling Send<TContext>(String, IBytes, ITopicSendOptions, TContext, ISendContextCallback<TContext>) with no send options.
Send<TContext>(String, IBytes, ITopicSendOptions, TContext, ISendContextCallback<TContext>)
Sends a message.
Declaration
void Send<TContext>(string topicPath, IBytes message, ITopicSendOptions options, TContext context, ISendContextCallback<TContext> callback)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The topic path to send the message to. |
IBytes | message | The message to send. This can be any subtype of IBytes, for example IBinary or IJSON. |
ITopicSendOptions | options | The options for sending the given message. |
TContext | context | The context passed to the callback with the reply to allow requests and replies to be correlated. The caller may use any convenient object reference, including 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>(String, TRequest) instead. This method will be removed in a future release.
Send<TContext>(String, String, TContext, ISendContextCallback<TContext>)
Sends a message.
Declaration
void Send<TContext>(string topicPath, string message, TContext context, ISendContextCallback<TContext> callback)
Parameters
Type | Name | Description |
---|---|---|
String | topicPath | The topic path to send the message to. |
String | message | The message to send. |
TContext | context | The context passed to the callback with the reply to allow requests and replies to be correlated. The caller may use any convenient object reference, including 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>(String, TRequest) instead. This method will be removed in a future release.
This is equivalent to calling Send<TContext>(String, IBytes, ITopicSendOptions, TContext, ISendContextCallback<TContext>) with string content and no send options.
Since 5.3
SendRequestAsync<TRequest, TResponse>(String, TRequest)
Sends the request.
Declaration
Task<TResponse> SendRequestAsync<TRequest, TResponse>(string path, TRequest request)
Parameters
Type | Name | Description |
---|---|---|
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
response. 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>(String, TRequest, CancellationToken)
Sends the request.
Declaration
Task<TResponse> SendRequestAsync<TRequest, TResponse>(string path, TRequest request, CancellationToken cancellationToken)
Parameters
Type | Name | Description |
---|---|---|
String | path | The path to send a request to. |
TRequest | request | The request to send. |
CancellationToken | cancellationToken | The cancellation token for 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
response. 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. |
SetRequestStream<TRequest, TResponse>(String, IRequestStream<TRequest, TResponse>)
Sets the requestStream
to handle requests to a specified path
(replacing stream
previously set for this path if any).
Declaration
IStream SetRequestStream<TRequest, TResponse>(string path, IRequestStream<TRequest, TResponse> requestStream)
Parameters
Type | Name | Description |
---|---|---|
String | path | Path to receive requests on. |
IRequestStream<TRequest, TResponse> | requestStream | Request stream to handle requests to this path. |
Returns
Type | Description |
---|---|
IStream | The stream registered previously for the |
Type Parameters
Name | Description |
---|---|
TRequest | |
TResponse |
Remarks
Since 6.1