Diffusion Apple API  6.9.0
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
PTDiffusionSubscriptionControlFeature Class Reference

Introduction

The Subscription Control feature allows a client session to subscribe or unsubscribe other sessions to topics, as well as also providing a mechanism for handling requests to subscribe to routing topics (deprecated).

The Subscription Control feature for a session can be obtained from the session's PTDiffusionSession::subscriptionControl property.

Requests to subscribe sessions to topics can be submitted at any time even if the topics do not exist at the server. Topic selectors are used on subscription to match against topics at the server. The session will become subscribed to any topics that exist at the server that match the selector (unless they are already subscribed, or the session has insufficient permission). The subscription request is also retained at the server so that if any newly created topics match the selector, the session will then become subscribed to it (unless a subsequent unsubscription cancels it).

Specific sessions may be subscribed/unsubscribed if the PTDiffusionSessionId is known.

Subscriptions may also be requested using session filters, where all sessions that satisfy a particular filter expression will be subscribed/unsubscribed. The filter is only evaluated once against the current sessions that exist at the time - it is not retained and applied to any sessions that are created later. In order to be notified of new sessions as they are created a PTDiffusionSessionPropertiesListener can be used and those sessions subscribed as required based upon their session properties.

A handler for routing topics belonging to a branch of the topic tree can be added using this feature's 'add routing subscription handler' method. When another session subscribes to one of the routing topics, the handler will be called to determine the appropriate source topic.

Access control

To subscribe other sessions to topics, a session must have modifySession (PTDiffusionGlobalPermission) permission, and selectTopic (PTDiffusionPathPermission) permission for the path prefix of the topic selector used for subscription. The subscribed sessions will only be subscribed to matching topics for which they have readTopic (PTDiffusionPathPermission) permission.

To unsubscribe other sessions, a session must have modifySession (PTDiffusionGlobalPermission) permission.

To register a routing subscription handler the session needs viewSession (PTDiffusionGlobalPermission), modifySession (PTDiffusionGlobalPermission) and registerHandler (PTDiffusionGlobalPermission) permissions.

When handling a subscription request to a routing topic via a routing handler the target session needs readTopic (PTDiffusionPathPermission) permission to both the routing topic being subscribed to and the target topic that is assigned.

Since
6.1
Inheritance diagram for PTDiffusionSubscriptionControlFeature:
PTDiffusionFeature

Instance Methods

(void) - subscribeSessionId:withTopicSelectorExpression:completionHandler:
 
(void) - unsubscribeSessionId:withTopicSelectorExpression:completionHandler:
 
(void) - subscribeWithFilter:topicSelectorExpression:completionHandler:
 
(void) - unsubscribeWithFilter:topicSelectorExpression:completionHandler:
 
(PTDiffusionStream *) - addRoutingRequestHandler:forTopicPath:completionHandler:
 

Additional Inherited Members

- Properties inherited from PTDiffusionFeature
PTDiffusionSessionsession
 

Method Documentation

- (PTDiffusionStream *) addRoutingRequestHandler: (id< PTDiffusionSubscriptionRoutingRequestHandler >)  handler
forTopicPath: (NSString *)  topicPath
completionHandler: (PTDiffusionRegistration *_Nullable)  registration
(NSError *_Nullable error)  completionHandler 

Adds a handler for routing topics that belong to a branch of the topic tree. When another session subscribes to one of the routing topics, the handler will be called to determine the appropriate source topic.

For each subscription to the routing topic, the server will select a handler registered for the most specific branch. If multiple handlers are registered for the same branch, the server will select one of them arbitrarily.

Parameters
handlerThe object which will handle the incoming subscription routing requests. It will be sent messages asynchronously on the main dispatch queue. A weak reference is maintained to this object.
topicPathIdentifies the branch of the topic tree to associate the handler with.
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 point to a registration object which can be used to manage the registration. The completion handler will be called asynchronously on the main dispatch queue.
Returns
Stream resulting from the registration of the given routing request handler for the given topic path.
Exceptions
NSInvalidArgumentExceptionRaised if any arguments are nil.
Since
6.1
Deprecated:
since 6.7 Routing Topics are deprecated. The more powerful Session Trees feature should be used in their place.
- (void) subscribeSessionId: (PTDiffusionSessionId *)  sessionId
withTopicSelectorExpression: (NSString *)  expression
completionHandler: (NSError *_Nullable error)  completionHandler 

Subscribe another session to topics.

New subscriptions will be established for existing topics that match the provided topic selector and for which the subscribed session has readTopic (PTDiffusionPathPermission) permission. The topic selector will be added to the topic selections of the subscribed session, and re-evaluated when new topics are added or the session's security roles change.

A session that does not have selectTopic (PTDiffusionPathPermission) permission for a topic cannot subscribe directly, but can be subscribed indirectly using this method.

Parameters
sessionIdIdentifies the session to subscribe.
expressionThe topic selector expression to be evaluated by the server, identifying the topics to subscribe to.
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
6.1
- (void) subscribeWithFilter: (NSString *)  filter
topicSelectorExpression: (NSString *)  expression
completionHandler: (NSUInteger)  count
(NSError *_Nullable error)  completionHandler 

Subscribe sessions that satisfy a given session filter to topics.

For each session that matches the filter, new subscriptions will be established for existing topics that match the provided topic selector and for which the sessions has readTopic (PTDiffusionPathPermission) permission. The topic selector will be added to the topic selections of the subscribed session, and re-evaluated when new topics are added or the session's security roles change.

A session that does not have selectTopic (PTDiffusionPathPermission) permission for a topic cannot subscribe directly, but can be subscribed indirectly using this method.

Parameters
filterThe session filter expression.
expressionThe topic selector expression to be evaluated by the server, identifying the topics to subscribe to.
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 count argument indicates the number of clients that satisfied the filter and qualified for subscription. On failure the error argument passed to the block will not be nil and the count argument will be zero. The completion handler will be called asynchronously on the main dispatch queue.
Note
The completion handler block will be invoked with a nil for the error argument and zero for the count argument if no client sessions satisified the filter.
Exceptions
NSInvalidArgumentExceptionIf any arguments are nil.
Since
6.1
- (void) unsubscribeSessionId: (PTDiffusionSessionId *)  sessionId
withTopicSelectorExpression: (NSString *)  expression
completionHandler: (NSError *_Nullable error)  completionHandler 

Unsubscribe another session from topics.

Parameters
sessionIdIdentifies the session to unsubscribe.
expressionThe topic selector expression to be evaluated by the server, identifying the topics to unsubscribe from.
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
6.1
- (void) unsubscribeWithFilter: (NSString *)  filter
topicSelectorExpression: (NSString *)  expression
completionHandler: (NSUInteger)  count
(NSError *_Nullable error)  completionHandler 

Unsubscribe sessions that satisfy a given session filter from topics.

Parameters
filterThe session filter expression.
expressionThe topic selector expression to be evaluated by the server, identifying the topics to unsubscribe from.
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 count argument indicates the number of clients that satisfied the filter and qualified for unsubscription. On failure the error argument passed to the block will not be nil and the count argument will be zero. The completion handler will be called asynchronously on the main dispatch queue.
Note
The completion handler block will be invoked with a nil for the error argument and zero for the count argument if no client sessions satisified the filter.
Exceptions
NSInvalidArgumentExceptionIf any arguments are nil.
Since
6.1