Request-response messaging

You can send request messages directly to a client session, a set of client sessions, or a message path. The recipient of a message can respond to the request.

Concepts

Request: A message sent from one client session to another session, to a message path, or to a set of sessions.
Response: A message sent in reply to a request message.
Data type: Request and response messages can contain data of one of the following types: JSON, binary, string, 64-bit integer, or double.
The response message is not required to be the same data type as the request it responds to.
Message path: The path used to address the request messages.
The message path is made up of path segments separated by the slash character (/). Each path segment can be made up of one or more Unicode characters.
Handler: An object registered by client session to handle requests sent on message paths in a specific branch of the path hierarchy, and to respond to those requests.
Stream: An object used by a client session to receive requests sent to that client session, and to respond to those requests.
Session properties: Properties assigned to a session, either by Diffusion™ Cloud or by an authentication handler. These properties can be used to select the set of sessions to send requests to.
For more information, see Session properties.

Send request messages in the following ways:

Send requests to a message path

A client session registers a handler on a part of the topic tree. This client session receives any requests that are sent on message paths in that part of the topic tree.

A client session with the send_to_message_handler permission can send requests on a message path. The sending client session does not know which client session, if any, receives the request.

A client session with the register_handler permission can register a handler on a part of the topic tree. This client session receives any requests that are sent on message paths in that part of the topic tree and sends a response.

For more information, see Sending request messages to a message path.

Send request messages to a specific client session

A client session that knows about other client sessions sends messages through a message path to those client sessions.

A client session with the send_to_session permission that knows the session ID of a client session can send requests through a message path to the known client session.

The responding client must have a request stream registered against a message path to receive requests sent through that message path and respond to them.

For more information, see Sending request messages to a session.

Send request messages to a set of client sessions

A client that knows about other client sessions sends requests through a message path to those client sessions filtered by their session properties.

A client session with the send_to_session permission can send requests through a message path to a filter that selects client sessions based on their session properties.

The responding client session must have a request stream registered against a message path to receive and respond to requests sent through that message path.

For more information, see Sending request messages to a session filter.

Considerations when using request-response messaging

The data type of the request is not required to match the data type of the response. For more information, see Typed requests and responses.
Messaging can use message paths that are the same as topic paths with topics bound to them. However, there is no connection between messaging and topics. For more information, see Message path.
When considering the format of your data, be aware that the maximum size for a topic update or a message sent through Diffusion Cloud is 1 MiB.