Represents a feature that provides a client session with messaging capabilities. More...

Inheritance diagram for PushTechnology.ClientInterface.Client.Features.IMessaging:

Public Member Functions
void	Send (string topicPath, string message, ISendCallback callback)
	Sends a message. More...

void	Send (string topicPath, IBytes message, ISendCallback callback)
	Sends a message. More...

void	Send (string topicPath, IBytes message, ITopicSendOptions options, ISendCallback callback)
	Sends a message. More...

void	Send< TContext > (string topicPath, string message, TContext context, ISendContextCallback< TContext > callback)
	Sends a message. More...

void	Send< TContext > (string topicPath, IBytes message, TContext context, ISendContextCallback< TContext > callback)
	Sends a message. More...

void	Send< TContext > (string topicPath, IBytes message, ITopicSendOptions options, TContext context, ISendContextCallback< TContext > callback)
	Sends a message. More...

Task< TResponse >	SendRequestAsync< TRequest, TResponse > (string path, TRequest request, CancellationToken cancellationToken)
	Sends the request. More...

Task< TResponse >	SendRequestAsync< TRequest, TResponse > (string path, TRequest request)
	Sends the request. More...

void	AddMessageStream (ITopicSelector topics, IMessageStream stream)
	Adds a message stream for messages received from the server on topics that match a given ITopicSelector. More...

void	AddMessageStream (string topics, IMessageStream stream)
	Adds a message stream for messages received from the server on topics that match the given topic selector expression. More...

void	AddFallbackMessageStream (IMessageStream stream)
	Adds a fallback message stream. More...

Callbacks.IStream	SetRequestStream< TRequest, TResponse > (string path, IRequestStream< TRequest, TResponse > requestStream)
	Sets the requestStream to handle requests to a specified path (replacing stream previously set for this path if any). More...

void	RemoveMessageStream (IMessageStream stream)
	Removes a message stream. More...

Callbacks.IStream	RemoveRequestStream (string path)
	Removes the request stream at a particular path. More...

ISet< IMessageStream >	GetStreamsForTopic (string topicPath)
	Returns the set of message streams that would be notified for a specified topic path. More...

Public Member Functions inherited from PushTechnology.ClientInterface.Client.Types.ISendOptionsBuilderFactory
ITopicSendOptionsBuilder	CreateSendOptionsBuilder ()
	Creates a new send options builder. More...

Additional Inherited Members
Properties inherited from PushTechnology.ClientInterface.Client.Features.IFeature
ISession	Session `[get]`
	Returns the session that the feature is associated with. More...

Detailed Description

Represents a feature that provides a client session with messaging capabilities.

Each message is delivered to a message handler registered with the server. Additionally, the server and other clients 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 topic path. The path provides a hierarchical context for the recipient. A topic with the path need not exist on the server; if one does exist, it is unaffected by messaging. An application can use the topic path to associate messages with topics, or an arbitrary path can be chosen. The path is also used for access control.

This feature provides the ability to:

Send a message associated with a topic path.

Sent messages are delivered to a message handler registered with the server for that topic path. If there is no registered message handler, the message is discarded.

Specify streams to receive messages on topic paths

A client can listen to messages for a selection of topics by adding one or more IMessageStream implementations. The mapping of topic selectors to message streams is maintained locally in the client process. Any number of message streams for inbound messages can be added on various topic selectors. If a message is received on a topic path that matches with no message streams, it is passed to any fallback message streams that have been registered.

A typical use case for messaging is a form of request/response paradigm where a message is sent and then a reply is returned. In this case it is important to set up suitable message streams for receiving messages before sending any messages.

Streams receive an IStream.OnClose callback when unregistered and an ICallback.OnDiscard callback if the session is closed).

Access control

A client session needs TopicPermission.SEND_TO_MESSAGE_HANDLER permission for the topic paths to which it sends messages. If a client sends messages to a topic path for which it does not have permission, the message is discarded by the server.

Accessing the feature

Obtain this feature from a ISession as follows:

var messaging = session.Messaging;

Since 5.0

Member Function Documentation

void PushTechnology.ClientInterface.Client.Features.IMessaging.AddFallbackMessageStream ( IMessageStream stream )

Adds a fallback message stream.

When a message is received from the server, it will be passed on to all message streams that have been added 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

Parameters

stream The message stream to add as a fallback stream.

void PushTechnology.ClientInterface.Client.Features.IMessaging.AddMessageStream	(	ITopicSelector	topics,
		IMessageStream	stream
	)

Adds a message stream for messages received from the server on topics that match a given ITopicSelector.

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 fallback message streams will be called instead.

Since 5.1

Parameters

topics	The selector of one or more topics.
stream	The stream to add.

void PushTechnology.ClientInterface.Client.Features.IMessaging.AddMessageStream	(	string	topics,
		IMessageStream	stream
	)

Adds a message stream for messages received from the server on topics that match the given topic selector expression.

This is equivalent to calling AddMessageStream(ITopicSelector,IMessageStream) with a selector parsed from the given string expression.

Since 5.1

Parameters

topics	The topics as a topic selector expression.
stream	The stream to add.

ISet<IMessageStream> PushTechnology.ClientInterface.Client.Features.IMessaging.GetStreamsForTopic ( string topicPath )

Returns the set of message streams that would be notified for a specified topic path.

Since 5.1

Parameters

topicPath The topic path.

Returns: the set of message streams that match the given topic path. If there are no matching streams, this set will be empty (the fallback message streams are not returned).

void PushTechnology.ClientInterface.Client.Features.IMessaging.RemoveMessageStream ( IMessageStream stream )

Removes a message stream.

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

Parameters

stream The message stream to remove.

Callbacks.IStream PushTechnology.ClientInterface.Client.Features.IMessaging.RemoveRequestStream ( string path )

Removes the request stream at a particular path.

Parameters

path	The path at which to remove the request stream.

Returns: 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), null will be returned instead.

Since 6.1

void PushTechnology.ClientInterface.Client.Features.IMessaging.Send	(	string	topicPath,
		string	message,
		ISendCallback	callback
	)

Sends a message.

This is equivalent to calling Send(string,IBytes,ITopicSendOptions,ISendCallback) with string content and no send options.

Since 5.3

Parameters

topicPath	The topic path to send the message to.
message	The message to send.
callback	The callback to receive operation status notifications.

void PushTechnology.ClientInterface.Client.Features.IMessaging.Send	(	string	topicPath,
		IBytes	message,
		ISendCallback	callback
	)

Sends a message.

This is equivalent to calling Send(string,IBytes,ITopicSendOptions,ISendCallback) with no send options.

Parameters

topicPath	The topic path to send the message to.
message	The message to send. This can be any subtype of IBytes, for example IBinary or IJSON.
callback	The callback to receive operation status notifications.

void PushTechnology.ClientInterface.Client.Features.IMessaging.Send	(	string	topicPath,
		IBytes	message,
		ITopicSendOptions	options,
		ISendCallback	callback
	)

Sends a message.

Parameters

topicPath	The topic path to send the message to.
message	The message to send. This can be any subtype of IBytes, for example IBinary or IJSON.
options	The options for sending the given message.
callback	The callback to receive operation status notifications.

void PushTechnology.ClientInterface.Client.Features.IMessaging.Send< TContext >	(	string	topicPath,
		string	message,
		TContext	context,
		ISendContextCallback< TContext >	callback
	)

Sends a message.

This is equivalent to calling Send{TContext}(string,IBytes,ITopicSendOptions,TContext,ISendContextCallback{TContext}) with string content and no send options.

Since 5.3

Template Parameters

TContext The context type.

Parameters

topicPath	The topic path to send the message to.
message	The message to send.
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.
callback	The callback to receive operation status notifications.

void PushTechnology.ClientInterface.Client.Features.IMessaging.Send< TContext >	(	string	topicPath,
		IBytes	message,
		TContext	context,
		ISendContextCallback< TContext >	callback
	)

Sends a message.

This is equivalent to calling Send{TContext}(string,IBytes,ITopicSendOptions,TContext,ISendContextCallback{TContext}) with no send options.

Template Parameters

TContext The context type.

Parameters

topicPath	The topic path to send the message to.
message	The message to send. This can be any subtype of IBytes, for example IBinary or IJSON.
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.
callback	The callback to receive operation status notifications.

void PushTechnology.ClientInterface.Client.Features.IMessaging.Send< TContext >	(	string	topicPath,
		IBytes	message,
		ITopicSendOptions	options,
		TContext	context,
		ISendContextCallback< TContext >	callback
	)

Sends a message.

Template Parameters

TContext The context type.

Parameters

topicPath	The topic path to send the message to.
message	The message to send. This can be any subtype of IBytes, for example IBinary or IJSON.
options	The options for sending the given message.
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.
callback	The callback to receive operation status notifications.

Task<TResponse> PushTechnology.ClientInterface.Client.Features.IMessaging.SendRequestAsync< TRequest, TResponse >	(	string	path,
		TRequest	request,
		CancellationToken	cancellationToken
	)

Sends the request.

Template Parameters

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

Parameters

path	The path to send a request to.
request	The request to send.
cancellationToken	The cancellation token for the Task returned.

<return>A Task that completes when a response has been received by a handler.</return>

If the Task completes successfully, its result will contain a TResponse response. Otherwise, the Task will complete with an exception.

Since 6.1

Exceptions

ArgumentException	There is no data type matching the request type parameter.
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.
ArgumentException	The response is not compatible with the specified response type. Thrown by the returned task.
RejectedRequestException	The request has been rejected by the recipient session calling IResponder{TResponse}.Reject(string). Thrown by the returned task.
SessionClosedException	The session is closed. Thrown by the returned task.
SessionSecurityException	The session does not have TopicPermission.SEND_TO_MESSAGE_HANDLER permission. Thrown by the returned task.
TimeoutException	The recipient session did not respond before the request timed out. Thrown by the returned task.

Task<TResponse> PushTechnology.ClientInterface.Client.Features.IMessaging.SendRequestAsync< TRequest, TResponse >	(	string	path,
		TRequest	request
	)

Sends the request.

Template Parameters

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

Parameters

path	The path to send a request to.
request	The request to send.

<return>A Task that completes when a response has been received by a handler.</return>

If the Task completes successfully, its result will contain a TResponse response. Otherwise, the Task will complete with an exception.

Since 6.1

Exceptions

ArgumentException	There is no data type matching the request type parameter.
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.
ArgumentException	The response is not compatible with the specified response type. Thrown by the returned task.
RejectedRequestException	The request has been rejected by the recipient session calling IResponder{TResponse}.Reject(string). Thrown by the returned task.
SessionClosedException	The session is closed. Thrown by the returned task.
SessionSecurityException	The session does not have TopicPermission.SEND_TO_MESSAGE_HANDLER permission. Thrown by the returned task.
TimeoutException	The recipient session did not respond before the request timed out. Thrown by the returned task.

Callbacks.IStream PushTechnology.ClientInterface.Client.Features.IMessaging.SetRequestStream< TRequest, TResponse >	(	string	path,
		IRequestStream< TRequest, TResponse >	requestStream
	)

Sets the requestStream to handle requests to a specified path (replacing stream previously set for this path if any).

Parameters

path	Path to receive requests on.
requestStream	Request stream to handle requests to this path.

Returns: The stream registered previously for the path (which is being replaced by the new specified request stream) or null if no stream was registered.

Since 6.1

The documentation for this interface was generated from the following file:

LegacyModule/Client/Features/IMessaging.cs

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation