 |
Diffusion Apple API
6.10.3
Unified Client Library for iOS, tvOS and OS X / macOS
|
|
Diffusion Apple API
6.10.3
Unified Client Library for iOS, tvOS and OS X / macOS
|
The Subscription Control feature allows a client session to subscribe or unsubscribe other sessions to topics.
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.
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.
Additional Inherited Members | |
 Properties inherited from PTDiffusionFeature | |
| PTDiffusionSession * | session |
| - (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.
| sessionId | Identifies the session to subscribe. |
| expression | The topic selector expression to be evaluated by the server, identifying the topics to subscribe to. |
| 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) 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.
| filter | The session filter expression. |
| expression | The topic selector expression to be evaluated by the server, identifying the topics to subscribe to. |
| 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 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. |
nil for the error argument and zero for the count argument if no client sessions satisified the filter.| NSInvalidArgumentException | If any arguments are nil. |
| - (void) unsubscribeSessionId: | (PTDiffusionSessionId *) | sessionId | |
| withTopicSelectorExpression: | (NSString *) | expression | |
| completionHandler: | (NSError *_Nullable error) | completionHandler | |
Unsubscribe another session from topics.
| sessionId | Identifies the session to unsubscribe. |
| expression | The topic selector expression to be evaluated by the server, identifying the topics to unsubscribe from. |
| 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) unsubscribeWithFilter: | (NSString *) | filter | |
| topicSelectorExpression: | (NSString *) | expression | |
| completionHandler: | (NSUInteger) | count | |
| (NSError *_Nullable error) | completionHandler | ||
Unsubscribe sessions that satisfy a given session filter from topics.
| filter | The session filter expression. |
| expression | The topic selector expression to be evaluated by the server, identifying the topics to unsubscribe from. |
| 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 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. |
nil for the error argument and zero for the count argument if no client sessions satisified the filter.| NSInvalidArgumentException | If any arguments are nil. |
1.8.5