PTDiffusionTopicsFeature Class Reference

Introduction

The Topics feature provides a client session with the capability to receive streamed topic updates and/or fetch the state of topics.

The Topics feature for a session can be obtained from the session's topics property.

See Also

PTDiffusionSession

Since

5.6

Inheritance diagram for PTDiffusionTopicsFeature:

Instance Methods
(nullable PTDiffusionStream *)	- fetchWithTopicSelectorExpression:delegate:
(void)	- getTopicDetailsWithTopicPath:level:completionHandler:
(void)	- subscribeWithTopicSelectorExpression:completionHandler:
(void)	- unsubscribeFromTopicSelectorExpression:completionHandler:
(PTDiffusionTopicStream *)	- addTopicStreamWithSelector:delegate:
(PTDiffusionTopicStream *)	- addTopicStreamWithSelectorExpression:delegate:
(BOOL)	- removeTopicStream:
(PTDiffusionTopicStream *)	- addFallbackTopicStreamWithDelegate:
(void)	- addFallbackStream:
(void)	- addStream:withSelector:
(BOOL)	- removeStream:

Additional Inherited Members
Properties inherited from PTDiffusionFeature
PTDiffusionSession *	session

Method Documentation

- (void) addFallbackStream:

(PTDiffusionValueStream *)

stream

When a matching update is received from the server for a topic, it will be passed on to all value streams that have been added with matching selectors. If no value stream is registered with a matching selector, the fallback value streams that have been registered using this method will be called instead.

Zero, one, or many fallback value streams can be set. If there is no fallback value stream, updates that match no other will be discarded.

Parameters

stream

Handler of value stream events not handled by an explicitly registered topic selector. The delegate associated with this stream will be sent messages asynchronously on the main dispatch queue.

Exceptions

NSInvalidArgumentException

Raised if the supplied stream argument is nil.

Since

5.9

- (PTDiffusionTopicStream *) addFallbackTopicStreamWithDelegate:

(id< PTDiffusionTopicStreamDelegate >)

delegate

When a topic update is received from the server, it will be passed on to all topic streams that have been added with matching selectors. If no topic stream is registered with a matching selector, the fallback topic streams that have been registered using this method will be called instead.

Zero, one, or many fallback topic streams can be set. If there is no fallback topic stream, updates that match no other will be discarded.

Parameters

delegate

Receiver of messages on topic 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 topic 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 removeTopicStream: 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 PTDiffusionTopicStream, being a new subclass of PTDiffusionStream.

Since

5.6

- (void) addStream:		(PTDiffusionValueStream *)	stream
withSelector:		(PTDiffusionTopicSelector *)	selector

Add a value stream to receive topic updates for topics that match the given topic selector.

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

Parameters

stream	Handler of value stream events against this selector. The delegate associated with this stream will be sent messages asynchronously on the main dispatch queue.
selector	The topic selector to be evaluated locally.

Exceptions

NSInvalidArgumentException

Raised if any supplied arguments are nil.

Since

5.9

- (PTDiffusionTopicStream *) addTopicStreamWithSelector:		(PTDiffusionTopicSelector *)	selector
delegate:		(id< PTDiffusionTopicStreamDelegate >)	delegate

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

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

Parameters

selector	The topic selector to be evaluated locally.
delegate	Receiver of messages on matching topic 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 removeTopicStream: 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 PTDiffusionTopicStream, being a new subclass of PTDiffusionStream.

Since

5.6

- (PTDiffusionTopicStream *) addTopicStreamWithSelectorExpression:		(NSString *)	expression
delegate:		(id< PTDiffusionTopicStreamDelegate >)	delegate

A convenience method wrapping a call to [self addTopicStreamWithSelector:delegate]

Parameters

expression	The topic selector expression to be evaluated locally.
delegate	Receiver of messages on matching topic 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.

Exceptions

NSInvalidArgumentException

Raised if any supplied arguments are nil.

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 removeTopicStream: method is required later on.

Since

5.9

- (nullable PTDiffusionStream *) fetchWithTopicSelectorExpression:		(NSString *)	expression
delegate:		(id< PTDiffusionFetchStreamDelegate >)	delegate

Fetch the current state of topics.

Parameters

expression	The topic selector expression to be evaluated by the server.
delegate	Receiver of messages relating to this fetch request. 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 removeTopicStream: method is required later on.

Note

This method will return nil if the session has been closed.

Exceptions

NSInvalidArgumentException

raised if any supplied arguments are nil.

Since

5.6

- (void) getTopicDetailsWithTopicPath:		(NSString *)	topicPath
level:		(PTDiffusionTopicDetailsLevel *)	level
completionHandler:		(PTDiffusionTopicDetails *_Nullable)	topicDetails
		(NSError *_Nullable error)	completionHandler

Get the details of the given topic.

Parameters

topicPath	The full path of the topic to be queried.
level	The level of detail required in the response.
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. When successful the topicDetails argument passed to the block will be nil if the topic is unknown. The completion handler will be called asynchronously on the main dispatch queue.

Exceptions

NSInvalidArgumentException

raised if any supplied arguments are nil.

Since

5.7

- (BOOL) removeStream:

(nullable PTDiffusionStream *)

stream

Remove a topic or value 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 the feature then calls to this method do nothing and return NO.

Since

5.9

- (BOOL) removeTopicStream:

(nullable PTDiffusionTopicStream *)

__deprecated

Remove a topic 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 PTDiffusionTopicStream, being a new subclass of PTDiffusionStream.

Since

5.6

Deprecated:

Since 5.9, replaced by removeStream:

- (void) subscribeWithTopicSelectorExpression:		(NSString *)	expression
completionHandler:		(NSError *_Nullable error)	completionHandler

Request subscription to topics.

Parameters

expression	The topic selector expression to be evaluated by the server.
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.6

- (void) unsubscribeFromTopicSelectorExpression:		(NSString *)	expression
completionHandler:		(NSError *_Nullable error)	completionHandler

Request unsubscription from topics.

Parameters

expression	The topic selector expression to be evaluated by the server.
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.6