Diffusion Apple API
6.5.13
Unified Client Library for iOS, tvOS and OS X / macOS
|
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.
Additional Inherited Members | |
Properties inherited from PTDiffusionFeature | |
PTDiffusionSession * | session |
- (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.
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. |
NSInvalidArgumentException | Raised if the supplied stream argument is nil . |
addFallBackStream:error:
- (BOOL) addFallbackStream: | (PTDiffusionValueStream *) | stream | |
error: | (NSError **) | error | |
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.
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. |
error | May be 'nil'. Is supplied then will contain reason on failure. |
NSInvalidArgumentException | Raised if the supplied stream argument is nil . |
- (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.
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. |
NSInvalidArgumentException | Raised if any supplied arguments are nil . |
addStream:withSelector:error:
- (BOOL) addStream: | (PTDiffusionValueStream *) | stream | |
withSelector: | (PTDiffusionTopicSelector *) | selector | |
error: | (NSError **) | error | |
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.
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. |
error | May be 'nil'. Is supplied then will contain reason on failure. |
NSInvalidArgumentException | Raised if any supplied arguments are nil . |
- (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.
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. |
expression | The topic selector expression to be evaluated locally. |
NSInvalidArgumentException | Raised if any supplied arguments are nil . |
addStream:withSelectorExpression:error:
- (BOOL) addStream: | (PTDiffusionValueStream *) | stream | |
withSelectorExpression: | (NSString *) | expression | |
error: | (NSError **) | error | |
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.
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. |
expression | The topic selector expression to be evaluated locally. |
error | May be 'nil'. Is supplied then will contain reason on failure. |
NSInvalidArgumentException | Raised if any supplied arguments are nil . |
- (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. }
- (nullable PTDiffusionStream *) fetchWithTopicSelectorExpression: | (NSString *) | expression | |
delegate: | (id< PTDiffusionFetchStreamDelegate >) | delegate | |
Fetch the current state of topics.
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. |
nil
if the session has been closed.NSInvalidArgumentException | raised if any supplied arguments are nil . |
- (BOOL) removeStream: | (nullable PTDiffusionStream *) | stream |
Remove a topic or value stream that was previously added using a topic selector or as a fallback.
stream | The stream to remove. |
YES
if the stream was removed.stream
argument is nil
or the stream has already been removed from the feature then calls to this method do nothing and return NO
.- (void) subscribeWithTopicSelectorExpression: | (NSString *) | expression | |
completionHandler: | (NSError *_Nullable error) | completionHandler | |
Request subscription to topics.
The session will become subscribed to each existing topic matching the selector unless the session is already subscribed to the topic, or the session does not have READ_TOPIC
permission for the topic path. For each topic to which the session becomes subscribed, a subscription notification and initial value (if any) will be delivered to registered value streams before the completion handler is called.
The subscription request is also retained at the server and the session will be automatically subscribed to newly created topics that match the selector (unless a subsequent unsubscription cancels the request).
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. |
NSInvalidArgumentException | Raised if any supplied arguments are nil . |
- (void) unsubscribeFromTopicSelectorExpression: | (NSString *) | expression | |
completionHandler: | (NSError *_Nullable error) | completionHandler | |
Request unsubscription from topics.
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. |
NSInvalidArgumentException | Raised if any supplied arguments are nil . |