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
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:
PTDiffusionFeature

Instance Methods

(nullable PTDiffusionStream *) - fetchWithTopicSelectorExpression:delegate:
 
(void) - subscribeWithTopicSelectorExpression:completionHandler:
 
(void) - unsubscribeFromTopicSelectorExpression:completionHandler:
 
(void) - addFallbackStream:
 
(void) - addStream:withSelector:
 
(void) - addStream:withSelectorExpression:
 
(BOOL) - removeStream:
 
(PTDiffusionFetchRequest *) - fetchRequest
 
- 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

- (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
streamHandler 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
NSInvalidArgumentExceptionRaised if the supplied stream argument is nil.
Since
5.9
- (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
streamHandler of value stream events against this selector. The delegate associated with this stream will be sent messages asynchronously on the main dispatch queue.
selectorThe topic selector to be evaluated locally.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
5.9
- (void) addStream: (PTDiffusionValueStream *)  stream
withSelectorExpression: (NSString *)  expression 

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

This convenience method calls addStream:withSelector: having constructed a PTDiffusionTopicSelector instance using the given expression.

Parameters
streamHandler of value stream events against this selector. The delegate associated with this stream will be sent messages asynchronously on the main dispatch queue.
expressionThe topic selector expression to be evaluated locally.
Exceptions
NSInvalidArgumentExceptionRaised if any supplied arguments are nil.
Since
6.0
- (PTDiffusionFetchRequest *) fetchRequest

Creates an unconfigured fetch request.

If the request is invoked by calling fetchWithTopicSelectorExpression:completionHandler: (PTDiffusionFetchRequest) the fetch result will provide the paths and types of all of the topics which the session has permission to read.

You will usually want to restrict the query to a subset of the topic tree, and to retrieve the topic values and/or properties. This is achieved by applying one or more of the builder methods to produce more refined requests.

For example (Swift):

topics.fetchRequest()
    .fetchStringValues(withTopicSelectorExpression: "*A/B//")
    {
        (result: PTDiffusionStringFetchResult?, error: Error?) in
        / / TODO Handle result, if not `nil`, otherwise handle error.
    }
Returns
a new unconfigured fetch request
Since
6.2
- (nullable PTDiffusionStream *) fetchWithTopicSelectorExpression: (NSString *)  expression
delegate: (id< PTDiffusionFetchStreamDelegate >)  delegate 

Fetch the current state of topics.

Parameters
expressionThe topic selector expression to be evaluated by the server.
delegateReceiver 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 later use of the removeStream: method is required.
Note
This method will return nil if the session has been closed.
Exceptions
NSInvalidArgumentExceptionraised if any supplied arguments are nil.
Deprecated:
Since 6.2. Prefer fetchRequest instead. Unlike this method, it supports additional query constraints, returns type-safe values and optionally allows topic properties to be returned in order to fetch the current state of topics.
Since
5.6
- (BOOL) removeStream: (nullable PTDiffusionStream *)  stream

Remove a topic or value 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 the feature then calls to this method do nothing and return NO.
Since
5.9
- (void) subscribeWithTopicSelectorExpression: (NSString *)  expression
completionHandler: (NSError *_Nullable error)  completionHandler 

Request subscription to topics.

Parameters
expressionThe topic selector expression to be evaluated by the server.
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
5.6
- (void) unsubscribeFromTopicSelectorExpression: (NSString *)  expression
completionHandler: (NSError *_Nullable error)  completionHandler 

Request unsubscription from topics.

Parameters
expressionThe topic selector expression to be evaluated by the server.
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
5.6