Diffusion Apple API  6.2.0
Unified Client Library for iOS, tvOS and OS X / macOS
 All Classes Functions Variables Properties Pages
Instance Methods | List of all members
PTDiffusionMessagingFeature Class Reference

Introduction

The Messaging feature provides a client session with messaging capabilities.

The Messaging feature for a session can be obtained from the session's messaging property.

Each message is delivered to a request stream 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 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.

For more detail, see: Messaging with the Apple client library.

See Also
PTDiffusionSession
Since
5.6
Inheritance diagram for PTDiffusionMessagingFeature:
PTDiffusionFeature

Instance Methods

(void) - sendWithPath:value:options:completionHandler:
 
(void) - sendWithPath:value:completionHandler:
 
(PTDiffusionMessageStream *) - addMessageStreamWithSelector:delegate:
 
(BOOL) - removeMessageStream:
 
(PTDiffusionMessageStream *) - addFallbackMessageStreamWithDelegate:
 
(nullable
PTDiffusionRequestStream *) 
- setRequestStream:forPath:
 
(nullable
PTDiffusionRequestStream *) 
- removeRequestStreamForPath:
 
(void) - sendRequest:toPath:binaryCompletionHandler:
 
(void) - sendRequest:toPath:JSONCompletionHandler:
 
(void) - sendRequest:toPath:stringCompletionHandler:
 
(void) - sendRequest:toPath:doubleFloatNumberCompletionHandler:
 
(void) - sendRequest:toPath:int64NumberCompletionHandler:
 
(void) - sendRequest:toPath:recordCompletionHandler:
 
- Instance Methods inherited from PTDiffusionFeature
(instancetype) - NS_UNAVAILABLE
 

Additional Inherited Members

- Class Methods inherited from PTDiffusionFeature
(instancetype) + NS_UNAVAILABLE
 
- Properties inherited from PTDiffusionFeature
PTDiffusionSessionsession
 

Method Documentation

- (PTDiffusionMessageStream *) addFallbackMessageStreamWithDelegate: (id< PTDiffusionMessageStreamDelegate >)  delegate

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 will be discarded.

Parameters
delegateReceiver of messages stream events not handled by an explicitly registered topic selector. Used by the stream to notify of events but not retained. The delegate will be sent messages asynchronously on the main dispatch queue.
Returns
A new message stream instance configured to notify the delegate of events. This does not need to be retained by the caller, but should be if use with the removeMessageStream: method is required later on.
Exceptions
NSInvalidArgumentExceptionRaised if the supplied delegate argument is nil.
Note
Since the addition of value streams for version 5.9, this method now returns instances of PTDiffusionMessageStream, being a new subclass of PTDiffusionStream.
Deprecated:
Since 6.2. One-way messaging has been deprecated in favor of request-response messaging. This method will be removed in a future release.
Since
5.6
- (PTDiffusionMessageStream *) addMessageStreamWithSelector: (PTDiffusionTopicSelector *)  selector
delegate: (id< PTDiffusionMessageStreamDelegate >)  delegate 

Add a message stream to receive messages for topics that match the given topic selector.

When a message is received from the server, it will be passed to all message streams that have been added with matching selectors. If there is more than one match, the order in which the message streams are called is not defined. If there is no matching message stream, the fallback message stream will be called instead.

Parameters
selectorThe topic selector to be evaluated locally.
delegateReceiver of messages on matching message stream events. Used by the stream to notify of events but not retained. The delegate will be sent messages asynchronously on the main dispatch queue.
Returns
A new stream instance configured to notify the delegate of events. This does not need to be retained by the caller, but should be if use with the removeMessageStream: method is required later on.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Note
Since the addition of value streams for version 5.9, this method now returns instances of PTDiffusionMessageStream, being a new subclass of PTDiffusionStream.
Deprecated:
Since 6.2. One-way messaging has been deprecated in favor of request-response messaging. This method will be removed in a future release.
Since
5.6
- (BOOL) removeMessageStream: (nullable PTDiffusionMessageStream *)  stream

Remove a message stream that was previously added using a topic selector or as a fallback.

Parameters
streamThe stream to remove.
Returns
YES if the stream was removed.
Note
If the supplied stream argument is nil or the stream has already been removed from this feature then calls to this method do nothing and return NO.
Since the addition of value streams for version 5.9, this method now only accepts instances of PTDiffusionMessageStream, being a new subclass of PTDiffusionStream.
Deprecated:
Since 6.2. One-way messaging has been deprecated in favor of request-response messaging. This method will be removed in a future release.
Since
5.6
- (nullable PTDiffusionRequestStream *) removeRequestStreamForPath: (NSString *)  path

Remove the request stream mapped to the given path.

Parameters
pathThe path for which any request stream mapping should be removed.
Returns
The previously set request stream for the given path, or nil if there was not an existing dispatch mapping.
Since
6.0
- (void) sendRequest: (PTDiffusionRequest *)  request
toPath: (NSString *)  path
binaryCompletionHandler: (PTDiffusionBinary *_Nullable)  binary
(NSError *_Nullable error)  completionHandler 

Send a request for which a binary response is expected.

The message will be routed to an appropriately registered control handler for the given path.

Parameters
requestThe request to send.
pathThe path to send the request to.
completionHandlerBlock to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
6.0

Provided by category PTDiffusionMessagingFeature(PTDiffusionBinary).

- (void) sendRequest: (PTDiffusionRequest *)  request
toPath: (NSString *)  path
doubleFloatNumberCompletionHandler: (NSNumber *_Nullable)  number
(NSError *_Nullable error)  completionHandler 

Send a request for which a double-precision floating point (Eight-byte IEEE 754) response is expected.

The message will be routed to an appropriately registered control handler for the given path.

Parameters
requestThe request to send.
pathThe path to send the request to.
completionHandlerBlock to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
6.0

Provided by category PTDiffusionMessagingFeature(PTDiffusionPrimitive).

- (void) sendRequest: (PTDiffusionRequest *)  request
toPath: (NSString *)  path
int64NumberCompletionHandler: (NSNumber *_Nullable)  number
(NSError *_Nullable error)  completionHandler 

Send a request for which a 64-bit integer response is expected.

The message will be routed to an appropriately registered control handler for the given path.

Parameters
requestThe request to send.
pathThe path to send the request to.
completionHandlerBlock to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
6.0

Provided by category PTDiffusionMessagingFeature(PTDiffusionPrimitive).

- (void) sendRequest: (PTDiffusionRequest *)  request
toPath: (NSString *)  path
JSONCompletionHandler: (PTDiffusionJSON *_Nullable)  json
(NSError *_Nullable error)  completionHandler 

Send a request for which a JSON response is expected.

The message will be routed to an appropriately registered control handler for the given path.

Parameters
requestThe request to send.
pathThe path to send the request to.
completionHandlerBlock to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
6.0

Provided by category PTDiffusionMessagingFeature(PTDiffusionJSON).

- (void) sendRequest: (PTDiffusionRequest *)  request
toPath: (NSString *)  path
recordCompletionHandler: (PTDiffusionRecordV2 *_Nullable)  record
(NSError *_Nullable error)  completionHandler 

Send a request for which a record response is expected.

The message will be routed to an appropriately registered control handler for the given path.

Parameters
requestThe request to send.
pathThe path to send the request to.
completionHandlerBlock to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
6.0

Provided by category PTDiffusionMessagingFeature(PTDiffusionRecordV2).

- (void) sendRequest: (PTDiffusionRequest *)  request
toPath: (NSString *)  path
stringCompletionHandler: (NSString *_Nullable)  string
(NSError *_Nullable error)  completionHandler 

Send a request for which a string response is expected.

The message will be routed to an appropriately registered control handler for the given path.

Parameters
requestThe request to send.
pathThe path to send the request to.
completionHandlerBlock to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
6.0

Provided by category PTDiffusionMessagingFeature(PTDiffusionPrimitive).

- (void) sendWithPath: (NSString *)  path
value: (PTDiffusionBytes *)  value
completionHandler: (NSError *_Nullable error)  completionHandler 

Send a message using default send options.

The message will be routed to any appropriately registered control handlers for the given message path.

Parameters
pathThe message path to send to.
valueThe content of the message.
completionHandlerBlock to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Deprecated:
Since 6.2. One-way messaging has been deprecated in favor of request-response messaging. This method will be removed in a future release.
Since
6.0
- (void) sendWithPath: (NSString *)  path
value: (PTDiffusionBytes *)  value
options: (PTDiffusionSendOptions *)  options
completionHandler: (NSError *_Nullable error)  completionHandler 

Send a message.

The message will be routed to any appropriately registered control handlers for the given message path.

Parameters
pathThe message path to send to.
valueThe content of the message.
optionsThe send options to use.
completionHandlerBlock to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil. The completion handler will be called asynchronously on the main dispatch queue.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Deprecated:
Since 6.2. One-way messaging has been deprecated in favor of request-response messaging. This method will be removed in a future release.
Since
6.0
- (nullable PTDiffusionRequestStream *) setRequestStream: (PTDiffusionRequestStream *)  stream
forPath: (NSString *)  path 

Assign the request stream to handle requests sent to the given path.

Parameters
streamThe request stream which should be mapped to receive requests sent to the given path.
pathThe path for which received requests should be dispatched to the given request stream.
Returns
The previously set request stream for the given path, or nil if this is a fresh dispatch mapping.
Since
6.0