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

Introduction

The Topic Control feature provides a client session with the ability to manage topics.

The Topic Control feature for a session can be obtained from the session's topicControl property.

See Also
PTDiffusionSession
Since
5.7
Inheritance diagram for PTDiffusionTopicControlFeature:
PTDiffusionFeature

Instance Methods

(void) - addMissingTopicHandler:forTopicPath:completionHandler:
 
(void) - addTopicWithPath:type:completionHandler:
 
(void) - addTopicWithPath:specification:completionHandler:
 
(void) - addTopicEventListener:forTopicPath:completionHandler:
 
(void) - removeDiscreteWithTopicSelectorExpression:completionHandler:
 

Additional Inherited Members

- Properties inherited from PTDiffusionFeature
PTDiffusionSessionsession
 

Method Documentation

- (void) addMissingTopicHandler: (id< PTDiffusionMissingTopicHandler >)  handler
forTopicPath: (NSString *)  topicPath
completionHandler: (PTDiffusionTopicTreeRegistration *_Nullable)  registration
(NSError *_Nullable error)  completionHandler 

Register a handler of requests for a branch of the topic tree.

The provided handler is called when a client subscribes or fetches using a topic selector that matches no existing topics. This allows a control client to intercede when another session requests a topic that does not exist. The control client may use any of the add topic methods to create the topic, take some other action, or do nothing, before allowing the client operation to proceed by calling proceed. Alternatively, the control client can call cancel to discard the request.

A control client can register multiple handlers, but may only register a single handler for a given topic path. A handler will only be called for topic selectors with a path prefix that starts with or is equal to topicPath. If the path prefix matches multiple handlers, the one registered for the most specific (longest) topic path will be called.

Parameters
handlerThe handler to use for the topic tree branch identified by the given topicPath (unless overridden by a handler registered against a more specific branch).
topicPathIdentifies a branch of the topic tree.
completionHandlerBlock to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil and the registration argument will not be nil. The completion handler will be called asynchronously on the main dispatch queue.
Note
If the session is closing or closed when this method is called, the completion handler block will be called with an error, while the missing topic handler will receive no messages.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
5.7
- (void) addTopicEventListener: (id< PTDiffusionTopicEventListener >)  listener
forTopicPath: (NSString *)  topicPath
completionHandler: (PTDiffusionTopicTreeRegistration *_Nullable)  registration
(NSError *_Nullable error)  completionHandler 

Register a listener to receive topic events for a branch of the topic tree.

This allows a client to receive different events for topics. These events are emitted when a topic is subscribed to by one or more sessions after previously having no subscribers, or when a topic is no longer subscribed to by any session. These events are averaged over a small window of time to prevent rapid dispatch of events that ultimately return a topic to it's previous state.

Each control session may register a single handler for a branch.

Parameters
listenerSpecifies the listener for the specified branch (unless overriden by a listener registered against a more specific branch).
topicPathIdentifies a branch of the topic tree.
completionHandlerBlock to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil and the registration argument will not be nil. The completion handler will be called asynchronously on the main dispatch queue.
Note
If the session is closing or closed when this method is called, the completion handler block will be called with an error, while the topic event listener will receive no messages.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Deprecated:
Since 6.1. The main use case for this method was the removal of unused topics, now much better satisfied by using the removalPropertyKey (PTDiffusionTopicSpecification) with the subscriptions < n for condition. The removal topic property is fully cluster aware. This method will be removed in a future release.
Since
5.7
- (void) addTopicWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
completionHandler: (PTDiffusionAddTopicResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Send a request to the server to add a topic.

The topic will be initialized with the given value, if specified non-nil, during creation and therefore the value must be compatible with the topic type.

Parameters
pathThe full path of the topic to be created.
specificationDefines the topic to be created.
completionHandlerBlock to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil and result will be non-nil. The completion handler will be called asynchronously on the main dispatch queue.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or value has been supplied for a topic type that is not stateful.
Since
6.1
- (void) addTopicWithPath: (NSString *)  path
type: (PTDiffusionTopicType type
completionHandler: (PTDiffusionAddTopicResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Send a request to the server to add a topic.

This is a convenience method which creates the topic with default details for the given type.

Parameters
pathThe full path of the topic to be created.
typeThe type of topic to be created.
completionHandlerBlock to be called asynchronously on success or failure. If the operation was successful, the error argument passed to the block will be nil and result will be non-nil. The completion handler will be called asynchronously on the main dispatch queue.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or value has been supplied for a topic type that is not stateful.
Since
6.1
- (void) removeDiscreteWithTopicSelectorExpression: (NSString *)  expression
completionHandler: (NSError *_Nullable error)  completionHandler 

Send a request to remove one or more topics.

All topics that match the provided topic selector that the caller has permission to remove will be removed.

The selector's descendant pattern qualifier (a trailing / or //), can be used to remove descendant topics. If a single / qualifier is specified, all descendants of the matched topic paths will be removed. If // is specified, the matched paths and all descendants of the matched paths (complete branches) will be removed.

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
NSInvalidArgumentExceptionIf any argument is nil.
Since
5.9