Messaging is distinct from the publish/subscribe PTDiffusionTopicsFeature which provides streams of topic updates.

Messages are sent and received for a particular path. The message path provides a hierarchical context for the recipient.

Message paths are distinct from topic paths. A topic with the path need not exist on the server; if a topic does exist, it is unaffected by messaging. An application can use the same path to associate messages with topics, or an arbitrary path can be chosen.

Request-Response Messaging

Typed request-response messaging allows applications to send requests (of a specific data type) and receive responses (of the same or a different data type), handled by a completion handler block. Using Messaging, applications send requests to paths using the extension method supplied by the data type they expect to receive in response (e.g. PTDiffusionMessagingFeature::sendRequest:toPath:JSONCompletionHandler:).

In order to receive requests, applications must have a local request stream assigned to the specific path, using setRequestStream:forPath: (PTDiffusionMessagingFeature). When a request is received, the data type specific stream delegate is notified (e.g. PTDiffusionJSONRequestStreamDelegate), to which a response can be sent using the provided PTDiffusionResponder instance.

Access control

Messaging

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

Messaging Control

The message path is also used for access control. Authorization to send messages associated with a message path can be controlled using path-scoped permissions. This allows security roles to be granted to entire branches of the path hierarchy.

Sending a request/message to a specific session requires SEND_TO_SESSION permission. To add a request/message handler, the control client session must have REGISTER_HANDLER permissions and if registering to receive session property values, the session must also have VIEW_SESSION permissions.

Accessing Messaging features

PTDiffusionSession::messaging
PTDiffusionSession::messagingControl