PTDiffusionTopicUpdateControlFeature Class Reference

Introduction

The topic update control feature provides a client session with the capability to update topics at the server.

In order to update any topic the client must have suitable permissions for that topic.

A client does not have to be subscribed to a topic in order to update it.

Topics may be updated exclusively or non-exclusively. In exclusive mode the client registers as the update source for a particular branch of the topic tree and once registered no other client will be able to update topics in that branch. In non-exclusive mode a client may update any topic as long as there is no exclusive update source for its branch.

In either mode a PTDiffusionTopicUpdater is needed to send the updates. The way in which the updater is obtained is dependent upon the mode.

Updaters are thread-safe, but do not update topics from different threads as order can not be guaranteed.

Since

5.7

Inheritance diagram for PTDiffusionTopicUpdateControlFeature:

Properties
PTDiffusionTopicUpdater *	updater
	Returns an updater to be used for non-exclusive updating. More...
Properties inherited from PTDiffusionFeature
PTDiffusionSession *	session

Instance Methods
(void)	- registerUpdateSource:forTopicPath:completionHandler:
	Register an update source to be used for exclusive updating. More...
Instance Methods inherited from PTDiffusionFeature
(instancetype)	- NS_UNAVAILABLE

Additional Inherited Members
Class Methods inherited from PTDiffusionFeature
(instancetype)	+ NS_UNAVAILABLE

Method Documentation

- (void) registerUpdateSource:		(id< PTDiffusionTopicUpdateSource >)	updateSource
forTopicPath:		(NSString *)	topicPath
completionHandler:		(PTDiffusionTopicTreeRegistration *_Nullable)	registration
		(NSError *_Nullable error)	completionHandler

Register an update source to be used for exclusive updating.

Registers an object conforming to the PTDiffusionTopicUpdateSource protocol for a branch of the topic tree.

This registers the current client session as an update source for a specified branch of the topic tree, thus allowing updating of topics in that branch.

If the registration is successful the completion handler will be provided with a registration. This may be used to deregister the update source from the associated branch at a later point in time.

When an update source is registered, it will either be active or on standby, depending on the initial state that the server assigns. Subsequent state changes will result in further calls to these methods.

An update source is active when the server determines it is valid to send topic updates on the specified branch. In this case the update source is provided with a PTDiffusionTopicUpdater object to use to perform updates.

An update source is on standby when this source may no longer provide updates on the specified branch. Any updater instances previously provided to the update source are now invalid.

Parameters

updateSource	An object to be told when the active or on standby.
topicPath	The topic path to the branch of the topic tree to be exclusively updated by this update source when it's active.
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 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 update source will receive no messages.

Exceptions

NSInvalidArgumentException

If any arguments are nil.

Since

5.7

Property Documentation

- (PTDiffusionTopicUpdater*) updater

readnonatomicassign

Returns an updater to be used for non-exclusive updating.

The updater may be used to send updates to any topic that the client has permission to update. However, an update will fail if there is already a registered exclusive update source for the topic.

If more than one client sends non-exclusive updates to the same topic, the updates are performed on a last update wins basis.

Since

5.7