Represents a feature that provides a client session with the ability to use messaging functionality to communicate directly with other client sessions. More...

Inheritance diagram for PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl:

Public Member Functions
void	Send (ISessionId sessionId, string topicPath, IBytes message, ITopicSendOptions options, ISendCallback callback)
	Sends a message to a session via a specific topic. More...

void	Send (ISessionId sessionId, string topicPath, IBytes message, ISendCallback callback)
	Sends a message to a session via a specific topic. More...

void	Send (ISessionId sessionId, string topicPath, string message, ISendCallback callback)
	Sends a message to a session via a specific topic. More...

void	Send< TContext > (ISessionId sessionId, string topicPath, IBytes message, ITopicSendOptions options, TContext context, ISendContextCallback< TContext > callback)
	Sends message to a session via a specific topic. More...

void	Send< TContext > (ISessionId sessionId, string topicPath, IBytes message, TContext context, ISendContextCallback< TContext > callback)
	Sends message to a session via a specific topic. More...

void	Send< TContext > (ISessionId sessionId, string topicPath, string message, TContext context, ISendContextCallback< TContext > callback)
	Sends message to a session via a specific topic. More...

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

Task< TResponse >	SendRequestAsync< TRequest, TResponse > (ISessionId sessionId, string path, TRequest request)
	Sends a request. More...

void	AddMessageHandler (string topicPath, IMessageHandler handler, params string[] sessionProperties)
	Registers a message handler to handle messages received from other client sessions for a branch of the topic tree. More...

Task< IRegistration >	AddRequestHandlerAsync< TRequest, TResponse > (string path, IRequestHandler< TRequest, TResponse > handler, CancellationToken cancellationToken, params string[] sessionProperties)
	Registers a IRequestHandler{TRequest, TResponse} that will handle requests from other client sessions for a branch of the message path hierarchy. More...

Task< IRegistration >	AddRequestHandlerAsync< TRequest, TResponse > (string path, IRequestHandler< TRequest, TResponse > handler, params string[] sessionProperties)
	Registers a request handler to handle requests from other client sessions for a branch of the message path hierarchy. More...

void	SendToFilter (string filter, string topicPath, IBytes message, ITopicSendOptions options, ISendToFilterCallback callback)
	Sends a message to all sessions that satisfy a given session filter. More...

void	SendToFilter (string filter, string topicPath, IBytes message, ISendToFilterCallback callback)
	Sends a message to all sessions that satisfy a given session filter. More...

void	SendToFilter (string filter, string topicPath, string message, ISendToFilterCallback callback)
	Sends a message to all sessions that satisfy a given session filter. More...

void	SendToFilter< TContext > (string filter, string topicPath, IBytes message, ITopicSendOptions options, TContext context, ISendToFilterContextCallback< TContext > callback)
	Sends a message to all sessions that satisfy a given session filter. More...

void	SendToFilter< TContext > (string filter, string topicPath, IBytes message, TContext context, ISendToFilterContextCallback< TContext > callback)
	Sends a message to all sessions that satisfy a given session filter. More...

void	SendToFilter< TContext > (string filter, string topicPath, string message, TContext context, ISendToFilterContextCallback< TContext > callback)
	Sends a message to all sessions that satisfy a given session filter. More...

Task< int >	SendRequestToFilterAsync< TRequest, TResponse > (string filter, string path, TRequest request, IFilteredRequestCallback< TResponse > callback, CancellationToken cancellationToken)
	Sends a request to all sessions that satisfy a given session filter. More...

Task< int >	SendRequestToFilterAsync< TRequest, TResponse > (string filter, string path, TRequest request, IFilteredRequestCallback< TResponse > callback)
	Sends a request to all sessions that satisfy a given session filter. 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 the ability to use messaging functionality to communicate directly with other client sessions.

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

A 'message' comprises some IContent and/or some headers and may be sent with a specified priority.

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 can also be used to register handlers to receive messages sent from other clients. Different handlers may be registered to handle messages received on paths in different parts of the topic tree. Messages received from clients are delivered to the handler registered for the most specific topic path. If there multiple handlers are registered with the same path, a single one is chosen. If there are no matching handlers, the message is discarded.

A message sent directly to another session will be discarded if the receiving session is no longer connected or does not have a stream that matches the message's topic path. An error will be dispatched to the sending session error handler in this case.

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 within the IReceiveContext delivered with the message.

A typical use case for messaging is a form of request/response paradigm where a client sends a message to a path and it is delivered to a suitable handler which then sends a response to the originating client. Similarly, messages may be sent to clients to which responses are expected, in which case it is important to set up suitable handlers for the response before sending any messages.

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

Access control

To send messages to clients, the control client session needs to have TopicPermission.SEND_TO_SESSION permission for specified topic paths.

To add a message handler, the control client session needs to have GlobalPermission.REGISTER_HANDLER permissions and if registering to receive session property values it must also have GlobalPermission.VIEW_SESSION permissions.

Accessing the feature

This feature may be obtained from a ISession as follows:

var messagingControl = session.MessagingControl;

Since 5.0

Member Function Documentation

void PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.AddMessageHandler	(	string	topicPath,
		IMessageHandler	handler,
		params string[]	sessionProperties
	)

Registers a message handler to handle messages received from other client sessions for a branch of the topic tree.

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 (e.g. 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 ITopicTreeHandler.OnActive(string,IRegisteredHandler)). When the handler is no longer required, it may be closed using IRegisteredHandler.Close.To change the handler for a particular branch the previous handler must first be closed.

Parameters

topicPath	The topic path.
handler	The handler for all messages sent on topics beneath the specified branch (unless overridden by a handler registered against a more specific branch)
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.

Task<IRegistration> PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.AddRequestHandlerAsync< TRequest, TResponse >	(	string	path,
		IRequestHandler< TRequest, TResponse >	handler,
		CancellationToken	cancellationToken,
		params string[]	sessionProperties
	)

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

Template Parameters

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

Parameters

path The request message path.

handler Request handler to be registered at the server.

sessionProperties

A list of keys of session properties that should be supplied with each request. See

Parameters

cancellationToken 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 SessionControlConstants.AllFixedProperties as a key. In this case, any other fixed property keys are ignored. To request all user properties, include SessionControlConstants.AllUserProperties as a key. In this case, any other user properties are ignored.

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

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

Since 6.1

Exceptions

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.

Task<IRegistration> PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.AddRequestHandlerAsync< TRequest, TResponse >	(	string	path,
		IRequestHandler< TRequest, TResponse >	handler,
		params string[]	sessionProperties
	)

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 IRegistration.Close provided by the Task result. To change the handler for a particular branch the previous handler must first be closed.

Template Parameters

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

Parameters

path	The request message path.
handler	Request handler to be registered at the server.
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 SessionControlConstants.AllFixedProperties as a key. In this case, any other fixed property keys would be ignored. To request all user properties, include SessionControlConstants.AllUserProperties as a key. In this case, any other user properties are ignored.

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

Since 6.1

Exceptions

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.

void PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.Send	(	ISessionId	sessionId,
		string	topicPath,
		IBytes	message,
		ITopicSendOptions	options,
		ISendCallback	callback
	)

Sends a message to a session via a specific topic.

Parameters

sessionId	The session to send the message to.
topicPath	The topic path the message is associated with.
message	The message to send. This can be any subtype of IBytes, for example IContent, IBinary or IJSON.
options	The message options, including headers and priority.
callback	The callback to receive operation status notifications.

void PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.Send	(	ISessionId	sessionId,
		string	topicPath,
		IBytes	message,
		ISendCallback	callback
	)

Sends a message to a session via a specific topic.

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

Parameters

sessionId	The session to send the message to.
topicPath	The topic path the message is associated with.
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.Control.Topics.IMessagingControl.Send	(	ISessionId	sessionId,
		string	topicPath,
		string	message,
		ISendCallback	callback
	)

Sends a message to a session via a specific topic.

This is equivalent to calling Send(SessionId,string,IBytes,ISendCallback) with string content.

Since 5.3

Parameters

sessionId	The session to send the message to.
topicPath	The topic path the message is associated with.
message	The message to send.
callback	The callback to receive operation status notifications.

void PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.Send< TContext >	(	ISessionId	sessionId,
		string	topicPath,
		IBytes	message,
		ITopicSendOptions	options,
		TContext	context,
		ISendContextCallback< TContext >	callback
	)

Sends message to a session via a specific topic.

Template Parameters

TContext The context type.

Parameters

sessionId	The session to send the message to.
topicPath	The topic path the message is associated with.
message	The message to send. This can be any subtype of IBytes, for example IBinary or IJSON.
options	The message options, including headers and priority.
context	The context to pass to the callback. This may be null.
callback	The callback to receive operation status notifications.

void PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.Send< TContext >	(	ISessionId	sessionId,
		string	topicPath,
		IBytes	message,
		TContext	context,
		ISendContextCallback< TContext >	callback
	)

Sends message to a session via a specific topic.

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

Template Parameters

TContext The context type.

Parameters

sessionId	The session to send the message to.
topicPath	The topic path the message is associated with.
message	The message to send. This can be any subtype of IBytes, for example IBinary or IJSON.
context	The context to pass to the callback. This may be null.
callback	The callback to receive operation status notifications.

void PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.Send< TContext >	(	ISessionId	sessionId,
		string	topicPath,
		string	message,
		TContext	context,
		ISendContextCallback< TContext >	callback
	)

Sends message to a session via a specific topic.

This is equivalent to calling Send{TContext}(SessionId,string,IBytes,TContext,ISendContextCallback{TContext}) with string content.

Since 5.3

Template Parameters

TContext The context type.

Parameters

sessionId	The session to send the message to.
topicPath	The topic path the message is associated with.
message	The message to send.
context	The context to pass to the callback. This may be null.
callback	The callback to receive operation status notifications.

Task<TResponse> PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.SendRequestAsync< TRequest, TResponse >	(	ISessionId	sessionId,
		string	path,
		TRequest	request
	)

Sends a request.

Template Parameters

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

Parameters

sessionId	The session identifier.
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 be the response (to the request) of type TResponse . Otherwise, the Task will complete with an exception.

Since 6.1

Exceptions

ArgumentException	There is no data type matching the TRequest 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.Control.Topics.IMessagingControl.SendRequestAsync< TRequest, TResponse >	(	ISessionId	sessionId,
		string	path,
		TRequest	request,
		CancellationToken	cancellationToken
	)

Sends a request.

Template Parameters

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

Parameters

sessionId	The session identifier.
path	The path to send a request to.
request	The request to send.
cancellationToken	The CancellationToken for the Task created.

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

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

Since 6.1

Exceptions

ArgumentException	There is no data type matching the TRequest 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<int> PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.SendRequestToFilterAsync< TRequest, TResponse >	(	string	filter,
		string	path,
		TRequest	request,
		IFilteredRequestCallback< TResponse >	callback
	)

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

Template Parameters

TRequest	The request type.
TResponse	The response type.

Parameters

filter	The session filter expression.
path	Message path used by the recipient to select an appropriate handler.
request	The request object.
callback	The callback to receive notification of responses (or errors) from sessions.

Returns: A Task that completes when the server has dispatched all the requests.

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 <paramref="callback"/>. Otherwise, the Task will complete with an exception.

Exceptions

InvalidFilterException	The <paramref="filter"> parameter could not be parsed. Thrown by the returned task.
SessionSecurityException	The calling session does not have TopicPermission.SEND_TO_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

Task<int> PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.SendRequestToFilterAsync< TRequest, TResponse >	(	string	filter,
		string	path,
		TRequest	request,
		IFilteredRequestCallback< TResponse >	callback,
		CancellationToken	cancellationToken
	)

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

Template Parameters

TRequest	The request type.
TResponse	The response type.

Parameters

filter	The session filter expression.
path	Message path used by the recipient to select an appropriate handler.
request	The request object.
callback	The callback to receive notification of responses (or errors) from sessions.
cancellationToken	The cancellation token for the Task returned.

Returns: A Task that completes when the server has dispatched all the requests.

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 Task will complete with an exception.

Exceptions

InvalidFilterException	The <paramref="filter"> parameter could not be parsed. Thrown by the returned task.
SessionSecurityException	The calling session does not have TopicPermission.SEND_TO_SESSION permission. Thrown by the returned task.
SessionClosedException	The calling session is closed. Thrown by the returned task.

void PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.SendToFilter	(	string	filter,
		string	topicPath,
		IBytes	message,
		ITopicSendOptions	options,
		ISendToFilterCallback	callback
	)

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

Since 5.5

Parameters

filter	The session filter expression.
topicPath	The topic path the message is associated with.
message	The message to send. This can be any subtype of IBytes, for example IBinary or IJSON.
options	The message options, including headers and priority.
callback	The callback to receive operation status notifications.

void PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.SendToFilter	(	string	filter,
		string	topicPath,
		IBytes	message,
		ISendToFilterCallback	callback
	)

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

This is equivalent to calling SendToFilter(string,string,IBytes,ITopicSendOptions,ISendToFilterCallback) with default options.

Since 5.5

Parameters

filter	The session filter expression.
topicPath	The topic path the message is associated with.
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.Control.Topics.IMessagingControl.SendToFilter	(	string	filter,
		string	topicPath,
		string	message,
		ISendToFilterCallback	callback
	)

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

This is equivalent to calling SendToFilter(string,string,IBytes,ISendToFilterCallback) with string content.

Since 5.5

Parameters

filter	The session filter expression.
topicPath	The topic path the message is associated with.
message	The message to send.
callback	The callback to receive operation status notifications.

void PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.SendToFilter< TContext >	(	string	filter,
		string	topicPath,
		IBytes	message,
		ITopicSendOptions	options,
		TContext	context,
		ISendToFilterContextCallback< TContext >	callback
	)

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

Since 5.5

Template Parameters

TContext The context type.

Parameters

filter	The session filter expression.
topicPath	The topic path the message is associated with.
message	The message to send. This can be any subtype of IBytes, for example IBinary or IJSON.
options	The message options, including headers and priority.
context	The context to pass to the callback. This may be null.
callback	The callback to receive operation status notifications.

void PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.SendToFilter< TContext >	(	string	filter,
		string	topicPath,
		IBytes	message,
		TContext	context,
		ISendToFilterContextCallback< TContext >	callback
	)

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

This is equivalent to calling SendToFilter{TContext}(string,string,IBytes,ITopicSendOptions,TContext,ISendToFilterContextCallback{TContext}) with default options.

Since 5.5

Template Parameters

TContext The context type.

Parameters

filter	The session filter expression.
topicPath	The topic path the message is associated with.
message	The message to send. This can be any subtype of IBytes, for example IBinary or IJSON.
context	The context to pass to the callback. This may be null.
callback	The callback to receive operation status notifications.

void PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.SendToFilter< TContext >	(	string	filter,
		string	topicPath,
		string	message,
		TContext	context,
		ISendToFilterContextCallback< TContext >	callback
	)

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

This is equivalent to calling SendToFilter{TContext}(string,string,IBytes,TContext,ISendToFilterContextCallback{TContext}) with string content.

Since 5.5

Template Parameters

TContext The context type.

Parameters

filter	The session filter expression.
topicPath	The topic path the message is associated with.
message	The message to send.
context	The context to pass to the callback. This may be null.
callback	The callback to receive operation status notifications.

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

LegacyModule/Client/Features/Control/Topics/IMessagingControl.cs

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation