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...

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...

void	RemoveMessageStream (IMessageStream stream)
	Removes a message stream. 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]`
	Get the session that the service 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.GetMessagingFeature();

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.

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 IContent, 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 IContent, 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 IContent, 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 IContent, 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.

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

UCIStack/Client/Features/IMessaging.cs

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation