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.

See Also

PTDiffusionSession

Since

5.6

Inheritance diagram for PTDiffusionMessagingFeature:

Instance Methods
(void)	- sendWithTopicPath:content:options:completionHandler:
(void)	- sendWithTopicPath:value:options:completionHandler:
(void)	- sendWithTopicPath:content:completionHandler:
(void)	- sendWithTopicPath:value:completionHandler:
(PTDiffusionMessageStream *)	- addMessageStreamWithSelector:delegate:
(BOOL)	- removeMessageStream:
(PTDiffusionMessageStream *)	- addFallbackMessageStreamWithDelegate:

Additional Inherited Members
Properties inherited from PTDiffusionFeature
PTDiffusionSession *	session

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

delegate

Receiver 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

NSInvalidArgumentException

Raised 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.

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

selector	The topic selector to be evaluated locally.
delegate	Receiver 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

NSInvalidArgumentException

Raised 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.

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

stream

The 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.

Since

5.6

- (void) sendWithTopicPath:		(NSString *)	topicPath
content:		(PTDiffusionContent *)	content
completionHandler:		(NSError *_Nullable error)	__deprecated

Send an arbitrary message to the server on a particular topic path using default send options.

The path does not need to correspond to an existing topic; however the use of / as a hierarchical delimiter allows for other sessions to listen to messages from specific paths.

Parameters

topicPath	The topic path on which to send the message.
content	The content of the message.
completionHandler	Block 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

NSInvalidArgumentException

Raised if any supplied arguments are nil.

Deprecated:

since 5.9, replaced by sendWithTopicPath:value:completionHandler:

Since

5.6

- (void) sendWithTopicPath:		(NSString *)	topicPath
content:		(PTDiffusionContent *)	content
options:		(PTDiffusionSendOptions *)	options
completionHandler:		(NSError *_Nullable error)	__deprecated

Send an arbitrary message to the server on a particular topic path.

The path does not need to correspond to an existing topic; however the use of / as a hierarchical delimiter allows for other sessions to listen to messages from specific paths.

Parameters

topicPath	The topic path on which to send the message.
content	The content of the message.
options	The send options to use.
completionHandler	Block 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

NSInvalidArgumentException

Raised if any supplied arguments are nil.

Deprecated:

since 5.9, replaced by sendWithTopicPath:value:options:completionHandler:

Since

5.6

- (void) sendWithTopicPath:		(NSString *)	topicPath
value:		(PTDiffusionBytes *)	value
completionHandler:		(NSError *_Nullable error)	completionHandler

Send an arbitrary message to the server on a particular topic path using default send options.

The path does not need to correspond to an existing topic; however the use of / as a hierarchical delimiter allows for other sessions to listen to messages from specific paths.

Parameters

topicPath	The topic path on which to send the message.
value	The content of the message.
completionHandler	Block 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

NSInvalidArgumentException

Raised if any supplied arguments are nil.

Since

5.9

- (void) sendWithTopicPath:		(NSString *)	topicPath
value:		(PTDiffusionBytes *)	value
options:		(PTDiffusionSendOptions *)	options
completionHandler:		(NSError *_Nullable error)	completionHandler

Send an arbitrary message to the server on a particular topic path.

The path does not need to correspond to an existing topic; however the use of / as a hierarchical delimiter allows for other sessions to listen to messages from specific paths.

Parameters

topicPath	The topic path on which to send the message.
value	The content of the message.
options	The send options to use.
completionHandler	Block 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

NSInvalidArgumentException

Raised if any supplied arguments are nil.

Since

5.9