Diffusion .NET API
5.9.24
|
Represents a feature that provides a client session with the ability to use messaging functionality to communicate directly with other client sessions. More...
Public Member Functions | |
void | Send (SessionId sessionId, string topicPath, IBytes message, ITopicSendOptions options, ISendCallback callback) |
Sends a message to a session via a specific topic. More... | |
void | Send (SessionId sessionId, string topicPath, IBytes message, ISendCallback callback) |
Sends a message to a session via a specific topic. More... | |
void | Send (SessionId sessionId, string topicPath, string message, ISendCallback callback) |
Sends a message to a session via a specific topic. More... | |
void | Send< TContext > (SessionId 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 > (SessionId sessionId, string topicPath, IBytes message, TContext context, ISendContextCallback< TContext > callback) |
Sends message to a session via a specific topic. More... | |
void | Send< TContext > (SessionId sessionId, string topicPath, string message, TContext context, ISendContextCallback< TContext > callback) |
Sends message to a session via a specific topic. 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... | |
void | SendToFilter (string filter, string topicPath, IBytes message, ITopicSendOptions options, ISendToFilterCallback callback) |
Send a message to all sessions that satisfy a given session filter. More... | |
void | SendToFilter (string filter, string topicPath, IBytes message, ISendToFilterCallback callback) |
Send a message to all sessions that satisfy a given session filter. More... | |
void | SendToFilter (string filter, string topicPath, string message, ISendToFilterCallback callback) |
Send 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) |
Send 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) |
Send 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) |
Send a message 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] |
Get the session that the service is associated with. More... | |
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:
Since 5.0
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.
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. |
void PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.Send | ( | SessionId | sessionId, |
string | topicPath, | ||
IBytes | message, | ||
ITopicSendOptions | options, | ||
ISendCallback | callback | ||
) |
Sends a message to a session via a specific topic.
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 | ( | SessionId | 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.
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. |
callback | The callback to receive operation status notifications. |
void PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.Send | ( | SessionId | 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
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 > | ( | SessionId | sessionId, |
string | topicPath, | ||
IBytes | message, | ||
ITopicSendOptions | options, | ||
TContext | context, | ||
ISendContextCallback< TContext > | callback | ||
) |
Sends message to a session via a specific topic.
TContext | The context type. |
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. |
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 > | ( | SessionId | 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.
TContext | The context type. |
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. |
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 > | ( | SessionId | 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
TContext | The context type. |
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. |
void PushTechnology.ClientInterface.Client.Features.Control.Topics.IMessagingControl.SendToFilter | ( | string | filter, |
string | topicPath, | ||
IBytes | message, | ||
ITopicSendOptions | options, | ||
ISendToFilterCallback | callback | ||
) |
Send a message to all sessions that satisfy a given session filter.
Since 5.5
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 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.SendToFilter | ( | string | filter, |
string | topicPath, | ||
IBytes | message, | ||
ISendToFilterCallback | callback | ||
) |
Send 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
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 IContent, 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 | ||
) |
Send 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
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 | ||
) |
Send a message to all sessions that satisfy a given session filter.
Since 5.5
TContext | The context type. |
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 IContent, 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 | ||
) |
Send 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
TContext | The context type. |
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 IContent, 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 | ||
) |
Send 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
TContext | The context type. |
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. |