Diffusion Apple API  6.5.2
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
PTDiffusionTopicUpdateFeature Class Reference

Introduction

The Topic Update feature provides a client session with the ability to update topics.

Topics can be set to new values using stateless set operations or by using an update stream. Both mechanisms ensure that new values are applied safely to appropriate topics.

Update streams

An update stream is created for a specific topic. The type of the topic must match the type of values passed to the update stream. An update stream can be used to send any number of updates. It sends a sequence of updates for a specific topic to the server. If supported by the data type, updates will be sent to the server as a stream of binary deltas.

Update streams have additional ways of failing compared to stateless set operations but when used repeatedly have lower overheads. This is because update streams maintain a small amount of state that reduces the overhead of operations but can become invalid for example, if the topic is deleted, or some other session updates the topic value.

By default, update streams use a form of optimistic locking. An update stream can update its topic incrementally as long as nothing else updates the topic. If the topic is updated independently (for example, by another session, or by the current session via set or a different update stream), then the next update performed by the update stream will complete with an 'invalid update stream' error.

Applications can chose to use collaborative locking to coordinate exclusive access to a topic. To follow this pattern acquire a PTDiffusionSessionLock and use it with a lockedWithLock: (PTDiffusionUpdateConstraint) constraint. The application is responsible for designing a locking scheme which determines which lock is required to access a particular topic, and for ensuring that all parts of the application that update the topic follow this scheme. Lock constraints and an application locking scheme can also ensure a sequence of set operations has exclusive access to the topic.

Constraints

Constraints can be applied to the setting of a value and creation of an update stream. Constraints describe a condition that must be satisfied for the operation to succeed. The constraints are evaluated on the server. The available constraints are:

Removing values

When a PTDiffusionTopicType_String, PTDiffusionTopicType_Int64 or PTDiffusionTopicType_Double topic is set to nil, the topic will be updated to have no value. If a previous value was present subscribers will receive a notification that the new value is nil. New subscribers will not receive a value notification.

Adding topics

When setting a value using either stateless operations or update streams it is possible to add a topic if one is not present. This is done using the 'and and set' methods or providing a topic specification when creating the update stream. If a topic exists these methods will update the existing topic.

Time series topics

Time series topics have a specific update protocol and are not supported by this feature. Use PTDiffusionTimeSeriesFeature to update time series topics.

Access control

To update a topic a session needs UPDATE_TOPIC permission for the topic path. To create a topic a session needs MODIFY_TOPIC permission for the topic path. Requests that combine adding a topic and setting the value, such as those sent by the 'add and set' methods, require both permissions.

Accessing the feature

The Topic Update feature for a session can be obtained from the session's topicUpdate property.

This feature is also extended by PTDiffusionTopicsFeature. This means it is possible to use the methods described here through that feature.

See Also
PTDiffusionSession
Since
6.3
Inheritance diagram for PTDiffusionTopicUpdateFeature:
PTDiffusionFeature PTDiffusionTopicsFeature

Instance Methods

(void) - applyJsonPatch:toPath:completionHandler:
 
(void) - applyJsonPatch:toPath:withConstraint:completionHandler:
 
(void) - setWithPath:toBinaryValue:completionHandler:
 
(void) - setWithPath:toBinaryValue:constraint:completionHandler:
 
(void) - addWithPath:specification:andSetToBinaryValue:completionHandler:
 
(void) - addWithPath:specification:andSetToBinaryValue:constraint:completionHandler:
 
(PTDiffusionBinaryUpdateStream *) - binaryUpdateStreamWithPath:
 
(PTDiffusionBinaryUpdateStream *) - binaryUpdateStreamWithPath:constraint:
 
(PTDiffusionBinaryUpdateStream *) - binaryUpdateStreamWithPath:specification:
 
(PTDiffusionBinaryUpdateStream *) - binaryUpdateStreamWithPath:specification:constraint:
 
(void) - setWithPath:toJSONValue:completionHandler:
 
(void) - setWithPath:toJSONValue:constraint:completionHandler:
 
(void) - addWithPath:specification:andSetToJSONValue:completionHandler:
 
(void) - addWithPath:specification:andSetToJSONValue:constraint:completionHandler:
 
(PTDiffusionJSONUpdateStream *) - jsonUpdateStreamWithPath:
 
(PTDiffusionJSONUpdateStream *) - jsonUpdateStreamWithPath:constraint:
 
(PTDiffusionJSONUpdateStream *) - jsonUpdateStreamWithPath:specification:
 
(PTDiffusionJSONUpdateStream *) - jsonUpdateStreamWithPath:specification:constraint:
 
(BOOL) - setWithPath:toStringValue:completionHandler:error:
 
(void) - setWithPath:toDoubleValue:completionHandler:
 
(BOOL) - setWithPath:toDoubleFloatNumberValue:completionHandler:error:
 
(void) - setWithPath:toLongLongValue:completionHandler:
 
(BOOL) - setWithPath:toInt64NumberValue:completionHandler:error:
 
(BOOL) - setWithPath:toStringValue:constraint:completionHandler:error:
 
(void) - setWithPath:toDoubleValue:constraint:completionHandler:
 
(BOOL) - setWithPath:toDoubleFloatNumberValue:constraint:completionHandler:error:
 
(void) - setWithPath:toLongLongValue:constraint:completionHandler:
 
(BOOL) - setWithPath:toInt64NumberValue:constraint:completionHandler:error:
 
(BOOL) - addWithPath:specification:andSetToStringValue:completionHandler:error:
 
(void) - addWithPath:specification:andSetToDoubleValue:completionHandler:
 
(BOOL) - addWithPath:specification:andSetToDoubleFloatNumberValue:completionHandler:error:
 
(void) - addWithPath:specification:andSetToLongLongValue:completionHandler:
 
(BOOL) - addWithPath:specification:andSetToInt64NumberValue:completionHandler:error:
 
(BOOL) - addWithPath:specification:andSetToStringValue:constraint:completionHandler:error:
 
(void) - addWithPath:specification:andSetToDoubleValue:constraint:completionHandler:
 
(BOOL) - addWithPath:specification:andSetToDoubleFloatNumberValue:constraint:completionHandler:error:
 
(void) - addWithPath:specification:andSetToLongLongValue:constraint:completionHandler:
 
(BOOL) - addWithPath:specification:andSetToInt64NumberValue:constraint:completionHandler:error:
 
(PTDiffusionStringUpdateStream *) - stringUpdateStreamWithPath:
 
(PTDiffusionNumberUpdateStream *) - doubleFloatNumberUpdateStreamWithPath:
 
(PTDiffusionNumberUpdateStream *) - int64NumberUpdateStreamWithPath:
 
(PTDiffusionStringUpdateStream *) - stringUpdateStreamWithPath:constraint:
 
(PTDiffusionNumberUpdateStream *) - doubleFloatNumberUpdateStreamWithPath:constraint:
 
(PTDiffusionNumberUpdateStream *) - int64NumberUpdateStreamWithPath:constraint:
 
(PTDiffusionStringUpdateStream *) - stringUpdateStreamWithPath:specification:
 
(PTDiffusionNumberUpdateStream *) - doubleFloatNumberUpdateStreamWithPath:specification:
 
(PTDiffusionNumberUpdateStream *) - int64NumberUpdateStreamWithPath:specification:
 
(PTDiffusionStringUpdateStream *) - stringUpdateStreamWithPath:specification:constraint:
 
(PTDiffusionNumberUpdateStream *) - doubleFloatNumberUpdateStreamWithPath:specification:constraint:
 
(PTDiffusionNumberUpdateStream *) - int64NumberUpdateStreamWithPath:specification:constraint:
 
(void) - setWithPath:toRecordValue:completionHandler:
 
(void) - setWithPath:toRecordValue:constraint:completionHandler:
 
(void) - addWithPath:specification:andSetToRecordValue:completionHandler:
 
(void) - addWithPath:specification:andSetToRecordValue:constraint:completionHandler:
 
(PTDiffusionRecordV2UpdateStream *) - recordUpdateStreamWithPath:
 
(PTDiffusionRecordV2UpdateStream *) - recordUpdateStreamWithPath:constraint:
 
(PTDiffusionRecordV2UpdateStream *) - recordUpdateStreamWithPath:specification:
 
(PTDiffusionRecordV2UpdateStream *) - recordUpdateStreamWithPath:specification:constraint:
 

Additional Inherited Members

- Properties inherited from PTDiffusionFeature
PTDiffusionSessionsession
 

Method Documentation

- (void) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToBinaryValue: (PTDiffusionBinary *)  value
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Ensures a topic exists and sets it to a binary value.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toBinaryValue:completionHandler:.

Parameters
pathThe path of the topic.
valueThe value.
specificationThe required specification of the topic.
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 if the topic type defined in the specification is incompatible with binary (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionBinary).

- (void) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToBinaryValue: (PTDiffusionBinary *)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Ensures a topic exists and sets it to a binary value if a constraint is satisfied.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setTopicWithPath:toBinaryValue:constraint:completionHandler:.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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 if the topic type defined in the specification is incompatible with binary (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionBinary).

- (BOOL) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToDoubleFloatNumberValue: (nullable NSNumber *)  value
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler
error: (NSError **)  error 

Ensures a topic exists and sets it to a double-precision floating point (Eight-byte IEEE 754) number value, or null.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toJSONValue:completionHandler:.

Parameters
pathThe path of the topic.
valueThe value.
specificationThe required specification of the topic.
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.
errorIf this method returns NO to indicate that an error occured then this will be populated with the reason for that failure.
Returns
YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason.
Exceptions
NSInvalidArgumentExceptionIf any of the path, specification or completionHandler arguments are nil. Also if the topic type defined in the specification is incompatible with doubleFloat (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (BOOL) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToDoubleFloatNumberValue: (nullable NSNumber *)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler
error: (NSError **)  error 

Ensures a topic exists and sets it to a double-precision floating point (Eight-byte IEEE 754) number value, or null, if a constraint is satisfied.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toJSONValue:constraint:completionHandler:.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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.
errorIf this method returns NO to indicate that an error occured then this will be populated with the reason for that failure.
Returns
YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason.
Exceptions
NSInvalidArgumentExceptionIf any of the path, specification, constraint or completionHandler arguments are nil. Also if the topic type defined in the specification is incompatible with doubleFloat (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (void) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToDoubleValue: (double)  value
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Ensures a topic exists and sets it to a double-precision floating point (Eight-byte IEEE 754) value.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toJSONValue:completionHandler:.

Parameters
pathThe path of the topic.
valueThe value.
specificationThe required specification of the topic.
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 of the path, specification or completionHandler arguments are nil. Also if the topic type defined in the specification is incompatible with doubleFloat (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (void) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToDoubleValue: (double)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Ensures a topic exists and sets it to a double-precision floating point (Eight-byte IEEE 754) value if a constraint is satisfied.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toJSONValue:constraint:completionHandler:.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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 of the path, specification, constraint or completionHandler arguments are nil. Also if the topic type defined in the specification is incompatible with doubleFloat (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (BOOL) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToInt64NumberValue: (nullable NSNumber *)  value
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler
error: (NSError **)  error 

Ensures a topic exists and sets it to a 64-bit integer number value, or null.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toJSONValue:completionHandler:.

Parameters
pathThe path of the topic.
valueThe value.
specificationThe required specification of the topic.
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.
errorIf this method returns NO to indicate that an error occured then this will be populated with the reason for that failure.
Returns
YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason.
Exceptions
NSInvalidArgumentExceptionIf any of the path, specification or completionHandler arguments are nil. Also if the topic type defined in the specification is incompatible with int64 (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (BOOL) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToInt64NumberValue: (nullable NSNumber *)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler
error: (NSError **)  error 

Ensures a topic exists and sets it to a 64-bit integer number value, or null, if a constraint is satisfied.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toJSONValue:constraint:completionHandler:.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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.
errorIf this method returns NO to indicate that an error occured then this will be populated with the reason for that failure.
Returns
YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason.
Exceptions
NSInvalidArgumentExceptionIf any of the path, specification, constraint or completionHandler arguments are nil. Also if the topic type defined in the specification is incompatible with int64 (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (void) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToJSONValue: (PTDiffusionJSON *)  value
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Ensures a topic exists and sets it to a JSON value.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toJSONValue:completionHandler:.

Parameters
pathThe path of the topic.
valueThe value.
specificationThe required specification of the topic.
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 if the topic type defined in the specification is incompatible with json (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionJSON).

- (void) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToJSONValue: (PTDiffusionJSON *)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Ensures a topic exists and sets it to a JSON value if a constraint is satisfied.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toJSONValue:constraint:completionHandler:.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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 if the topic type defined in the specification is incompatible with json (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionJSON).

- (void) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToLongLongValue: (long long)  value
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Ensures a topic exists and sets it to a 64-bit integer value.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toJSONValue:completionHandler:.

Parameters
pathThe path of the topic.
valueThe value.
specificationThe required specification of the topic.
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 of the path, specification or completionHandler arguments are nil. Also if the topic type defined in the specification is incompatible with int64 (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (void) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToLongLongValue: (long long)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Ensures a topic exists and sets it to a 64-bit integer value if a constraint is satisfied.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toJSONValue:constraint:completionHandler:.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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 of the path, specification, constraint or completionHandler arguments are nil. Also if the topic type defined in the specification is incompatible with int64 (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (void) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToRecordValue: (PTDiffusionRecordV2 *)  value
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Ensures a topic exists and sets it to a record value.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toRecordValue:completionHandler:.

Parameters
pathThe path of the topic.
valueThe value.
specificationThe required specification of the topic.
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 if the topic type defined in the specification is incompatible with recordV2 (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionRecordV2).

- (void) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToRecordValue: (PTDiffusionRecordV2 *)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler 

Ensures a topic exists and sets it to a record value if a constraint is satisfied.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toRecordValue:constraint:completionHandler:.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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 if the topic type defined in the specification is incompatible with recordV2 (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionRecordV2).

- (BOOL) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToStringValue: (nullable NSString *)  value
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler
error: (NSError **)  error 

Ensures a topic exists and sets it to a string value, or null.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toJSONValue:completionHandler:.

Parameters
pathThe path of the topic.
valueThe value.
specificationThe required specification of the topic.
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.
errorIf this method returns NO to indicate that an error occured then this will be populated with the reason for that failure.
Returns
YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason.
Exceptions
NSInvalidArgumentExceptionIf any of the path, specification or completionHandler arguments are nil. Also if the topic type defined in the specification is incompatible with string (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (BOOL) addWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
andSetToStringValue: (nullable NSString *)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (PTDiffusionTopicCreationResult *_Nullable)  result
(NSError *_Nullable error)  completionHandler
error: (NSError **)  error 

Ensures a topic exists and sets it to a string value, or null, if a constraint is satisfied.

If a topic does not exist at the path, one will be created using the specification. If a topic does exist, its specification must match specification, otherwise the operation will fail.

In other respects this method works in the same way as setWithPath:toJSONValue:constraint:completionHandler:.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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.
errorIf this method returns NO to indicate that an error occured then this will be populated with the reason for that failure.
Returns
YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason.
Exceptions
NSInvalidArgumentExceptionIf any of the path, specification or completionHandler arguments are nil. Also if the topic type defined in the specification is incompatible with string (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (void) applyJsonPatch: (NSString *)  jsonPatch
toPath: (NSString *)  path
completionHandler: (PTDiffusionJSONPatchResult *)  result
(NSError *_Nullable error)  completionHandler 

Applies a JSON Patch to a JSON topic.

The patch argument should be formatted according to the JSON Patch standard (RFC 6902).

Patches are a sequence of JSON Patch operations contained in an array. They are applied as an atomic update to the previous value if the resulting update is successfully calculated. The following patch will check the value at a specific key and update if the expected value is correct:

[{"op":"test", "path":"/price", "value" : 22}, {"op":"add", "path":"/price", "value": 23}]

The available operations are:

  • Add: {"op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ]}
  • Remove: {"op": "remove", "path": "/a/b/c"}
  • Replace: {"op": "replace", "path": "/a/b/c", "value": 43}
  • Move: {"op": "move", "from": "/a/b/c", "path": "/a/b/d"}
  • Copy: {"op": "copy", "from": "/a/b/c", "path": "/a/b/e"}
  • Test: {"op": "test", "path": "/a/b/c", "value": "foo"}

The test operation checks that the CBOR representation of the value of a topic is identical to the value provided in the patch after converting it to CBOR. If the value is represented differently as CBOR, commonly due to different key ordering, then the patch will return the index of the failed operation . e.g the values {"foo": "bar", "count": 43} and {"count": 43, "foo": "bar"} are unequal despite semantic equality due to the differences in a byte for byte comparison.

Parameters
jsonPatchthe JSON Patch
paththe path of the topic to patch
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.
See Also
RFC 6902: JavaScript Object Notation (JSON) Patch
Since
6.4
- (void) applyJsonPatch: (NSString *)  jsonPatch
toPath: (NSString *)  path
withConstraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (PTDiffusionJSONPatchResult *)  result
(NSError *_Nullable error)  completionHandler 

Applies a JSON Patch to a JSON topic.

Takes a constraint that must be satisfied for the update to be applied.

In other respects this method works in the same way as applyJsonPatch:toPath:completionHandler:

Parameters
jsonPatchthe JSON Patch
paththe path of the topic to patch
constraintthe constraint that must be satisfied for the patch to be applied
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.
See Also
RFC 6902: JavaScript Object Notation (JSON) Patch
Since
6.4
- (PTDiffusionBinaryUpdateStream *) binaryUpdateStreamWithPath: (NSString *)  path

Creates an update stream to use for updating a specific topic with binary values.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionBinary).

- (PTDiffusionBinaryUpdateStream *) binaryUpdateStreamWithPath: (NSString *)  path
constraint: (PTDiffusionUpdateConstraint *)  constraint 

Creates an update stream to use for updating a specific topic with binary values if a constraint is satisfied.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
constraintThe constraint that must be satisfied for the update stream to be validated.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionBinary).

- (PTDiffusionBinaryUpdateStream *) binaryUpdateStreamWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification 

Creates an update stream to use for creating and updating a specific topic with binary values.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or if the topic type defined in the specification is incompatible with binary (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionBinary).

- (PTDiffusionBinaryUpdateStream *) binaryUpdateStreamWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
constraint: (PTDiffusionUpdateConstraint *)  constraint 

Creates an update stream to use for creating and updating a specific topic with binary values if a constraint is satisfied.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
constraintThe constraint that must be satisfied for the update stream to be validated.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or if the topic type defined in the specification is incompatible with binary (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionBinary).

- (PTDiffusionNumberUpdateStream *) doubleFloatNumberUpdateStreamWithPath: (NSString *)  path

Creates an update stream to use for updating a specific topic with double-precision floating point (Eight-byte IEEE 754) values.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

Creates an update stream to use for updating a specific topic with double-precision floating point (Eight-byte IEEE 754) values if a constraint is satisfied.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
constraintThe constraint that must be satisfied for the update stream to be validated.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (PTDiffusionNumberUpdateStream *) doubleFloatNumberUpdateStreamWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification 

Creates an update stream to use for creating and updating a specific topic with double-precision floating point (Eight-byte IEEE 754) values.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or the topic type defined in the specification is incompatible with doubleFloat (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (PTDiffusionNumberUpdateStream *) doubleFloatNumberUpdateStreamWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
constraint: (PTDiffusionUpdateConstraint *)  constraint 

Creates an update stream to use for creating and updating a specific topic with double-precision floating point (Eight-byte IEEE 754) values if a constraint is satisfied.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
constraintThe constraint that must be satisfied for the update stream to be validated.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or the topic type defined in the specification is incompatible with doubleFloat (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (PTDiffusionNumberUpdateStream *) int64NumberUpdateStreamWithPath: (NSString *)  path

Creates an update stream to use for updating a specific topic with 64-bit integer values.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (PTDiffusionNumberUpdateStream *) int64NumberUpdateStreamWithPath: (NSString *)  path
constraint: (PTDiffusionUpdateConstraint *)  constraint 

Creates an update stream to use for updating a specific topic with 64-bit integer values if a constraint is satisfied.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
constraintThe constraint that must be satisfied for the update stream to be validated.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (PTDiffusionNumberUpdateStream *) int64NumberUpdateStreamWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification 

Creates an update stream to use for creating and updating a specific topic with 64-bit integer values.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or the topic type defined in the specification is incompatible with int64 (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (PTDiffusionNumberUpdateStream *) int64NumberUpdateStreamWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
constraint: (PTDiffusionUpdateConstraint *)  constraint 

Creates an update stream to use for creating and updating a specific topic with 64-bit integer values if a constraint is satisfied.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
constraintThe constraint that must be satisfied for the update stream to be validated.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or the topic type defined in the specification is incompatible with int64 (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (PTDiffusionJSONUpdateStream *) jsonUpdateStreamWithPath: (NSString *)  path

Creates an update stream to use for updating a specific topic with JSON values.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf path is nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionJSON).

- (PTDiffusionJSONUpdateStream *) jsonUpdateStreamWithPath: (NSString *)  path
constraint: (PTDiffusionUpdateConstraint *)  constraint 

Creates an update stream to use for updating a specific topic with JSON values if a constraint is satisfied.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
constraintThe constraint that must be satisfied for the update stream to be validated.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf either argument is nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionJSON).

- (PTDiffusionJSONUpdateStream *) jsonUpdateStreamWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification 

Creates an update stream to use for creating and updating a specific topic with JSON values.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or if the topic type defined in the specification is incompatible with json (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionJSON).

- (PTDiffusionJSONUpdateStream *) jsonUpdateStreamWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
constraint: (PTDiffusionUpdateConstraint *)  constraint 

Creates an update stream to use for creating and updating a specific topic with JSON values if a constraint is satisfied.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
constraintThe constraint that must be satisfied for the update stream to be validated.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or if the topic type defined in the specification is incompatible with json (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionJSON).

- (PTDiffusionRecordV2UpdateStream *) recordUpdateStreamWithPath: (NSString *)  path

Creates an update stream to use for updating a specific topic with record values.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionRecordV2).

- (PTDiffusionRecordV2UpdateStream *) recordUpdateStreamWithPath: (NSString *)  path
constraint: (PTDiffusionUpdateConstraint *)  constraint 

Creates an update stream to use for updating a specific topic with record values if a constraint is satisfied.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
constraintThe constraint that must be satisfied for the update stream to be validated.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionRecordV2).

- (PTDiffusionRecordV2UpdateStream *) recordUpdateStreamWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification 

Creates an update stream to use for creating and updating a specific topic with record values.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or if the topic type defined in the specification is incompatible with recordV2 (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionRecordV2).

- (PTDiffusionRecordV2UpdateStream *) recordUpdateStreamWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
constraint: (PTDiffusionUpdateConstraint *)  constraint 

Creates an update stream to use for creating and updating a specific topic with record values if a constraint is satisfied.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
constraintThe constraint that must be satisfied for the update stream to be validated.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or if the topic type defined in the specification is incompatible with recordV2 (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionRecordV2).

- (void) setWithPath: (NSString *)  path
toBinaryValue: (PTDiffusionBinary *)  value
completionHandler: (NSError *_Nullable error)  completionHandler 

Sets a topic to a specified binary value.

Parameters
pathThe path of the topic.
valueThe value.
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
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionBinary).

- (void) setWithPath: (NSString *)  path
toBinaryValue: (PTDiffusionBinary *)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (NSError *_Nullable error)  completionHandler 

Sets a topic to a specified binary value if a constraint is satisfied.

Parameters
pathThe path of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionBinary).

- (BOOL) setWithPath: (NSString *)  path
toDoubleFloatNumberValue: (nullable NSNumber *)  value
completionHandler: (NSError *_Nullable error)  completionHandler
error: (NSError **)  error 

Sets a topic to a specified double-precision floating point (Eight-byte IEEE 754) number value, or null.

Parameters
pathThe path of the topic.
valueThe value.
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.
errorIf this method returns NO to indicate that an error occured then this will be populated with the reason for that failure.
Returns
YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason.
Exceptions
NSInvalidArgumentExceptionIf either path or completionHandler are nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (BOOL) setWithPath: (NSString *)  path
toDoubleFloatNumberValue: (nullable NSNumber *)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (NSError *_Nullable error)  completionHandler
error: (NSError **)  error 

Sets a topic to a specified double-precision floating point (Eight-byte IEEE 754) number value, or null, if a constraint is satisfied.

Parameters
pathThe path of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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.
errorIf this method returns NO to indicate that an error occured then this will be populated with the reason for that failure.
Returns
YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason.
Exceptions
NSInvalidArgumentExceptionIf any of path, constraint or completionHandler are nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (void) setWithPath: (NSString *)  path
toDoubleValue: (double)  value
completionHandler: (NSError *_Nullable error)  completionHandler 

Sets a topic to a specified double-precision floating point (Eight-byte IEEE 754) value.

Parameters
pathThe path of the topic.
valueThe value.
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 either path or completionHandler are nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (void) setWithPath: (NSString *)  path
toDoubleValue: (double)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (NSError *_Nullable error)  completionHandler 

Sets a topic to a specified double-precision floating point (Eight-byte IEEE 754) value if a constraint is satisfied.

Parameters
pathThe path of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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 of path, constraint or completionHandler are nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (BOOL) setWithPath: (NSString *)  path
toInt64NumberValue: (nullable NSNumber *)  value
completionHandler: (NSError *_Nullable error)  completionHandler
error: (NSError **)  error 

Sets a topic to a specified 64-bit integer number value, or null.

Parameters
pathThe path of the topic.
valueThe value.
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.
errorIf this method returns NO to indicate that an error occured then this will be populated with the reason for that failure.
Returns
YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason.
Exceptions
NSInvalidArgumentExceptionIf either path or completionHandler are nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (BOOL) setWithPath: (NSString *)  path
toInt64NumberValue: (nullable NSNumber *)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (NSError *_Nullable error)  completionHandler
error: (NSError **)  error 

Sets a topic to a specified 64-bit integer number value, or null, if a constraint is satisfied.

Parameters
pathThe path of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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.
errorIf this method returns NO to indicate that an error occured then this will be populated with the reason for that failure.
Returns
YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason.
Exceptions
NSInvalidArgumentExceptionIf any of path, constraint or completionHandler are nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (void) setWithPath: (NSString *)  path
toJSONValue: (PTDiffusionJSON *)  value
completionHandler: (NSError *_Nullable error)  completionHandler 

Sets a topic to a specified JSON value.

Parameters
pathThe path of the topic.
valueThe value.
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
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionJSON).

- (void) setWithPath: (NSString *)  path
toJSONValue: (PTDiffusionJSON *)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (NSError *_Nullable error)  completionHandler 

Sets a topic to a specified JSON value if a constraint is satisfied.

Parameters
pathThe path of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionJSON).

- (void) setWithPath: (NSString *)  path
toLongLongValue: (long long)  value
completionHandler: (NSError *_Nullable error)  completionHandler 

Sets a topic to a specified 64-bit integer value.

Parameters
pathThe path of the topic.
valueThe value.
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 either path or completionHandler are nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (void) setWithPath: (NSString *)  path
toLongLongValue: (long long)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (NSError *_Nullable error)  completionHandler 

Sets a topic to a specified 64-bit integer value if a constraint is satisfied.

Parameters
pathThe path of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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 of path, constraint or completionHandler are nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (void) setWithPath: (NSString *)  path
toRecordValue: (PTDiffusionRecordV2 *)  value
completionHandler: (NSError *_Nullable error)  completionHandler 

Sets a topic to a specified record value.

Parameters
pathThe path of the topic.
valueThe value.
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
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionRecordV2).

- (void) setWithPath: (NSString *)  path
toRecordValue: (PTDiffusionRecordV2 *)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (NSError *_Nullable error)  completionHandler 

Sets a topic to a specified record value if a constraint is satisfied.

Parameters
pathThe path of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionRecordV2).

- (BOOL) setWithPath: (NSString *)  path
toStringValue: (nullable NSString *)  value
completionHandler: (NSError *_Nullable error)  completionHandler
error: (NSError **)  error 

Sets a topic to a specified string value, or null.

Parameters
pathThe path of the topic.
valueThe value.
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.
errorIf this method returns NO to indicate that an error occured then this will be populated with the reason for that failure.
Returns
YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason.
Exceptions
NSInvalidArgumentExceptionIf either path or completionHandler are nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (BOOL) setWithPath: (NSString *)  path
toStringValue: (nullable NSString *)  value
constraint: (PTDiffusionUpdateConstraint *)  constraint
completionHandler: (NSError *_Nullable error)  completionHandler
error: (NSError **)  error 

Sets a topic to a specified string value, or null, if a constraint is satisfied.

Parameters
pathThe path of the topic.
valueThe value.
constraintThe constraint that must be satisfied for the topic to be updated.
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.
errorIf this method returns NO to indicate that an error occured then this will be populated with the reason for that failure.
Returns
YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason.
Exceptions
NSInvalidArgumentExceptionIf any of path, constraint or completionHandler are nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (PTDiffusionStringUpdateStream *) stringUpdateStreamWithPath: (NSString *)  path

Creates an update stream to use for updating a specific topic with string values.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (PTDiffusionStringUpdateStream *) stringUpdateStreamWithPath: (NSString *)  path
constraint: (PTDiffusionUpdateConstraint *)  constraint 

Creates an update stream to use for updating a specific topic with string values if a constraint is satisfied.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
constraintThe constraint that must be satisfied for the update stream to be validated.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil.
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (PTDiffusionStringUpdateStream *) stringUpdateStreamWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification 

Creates an update stream to use for creating and updating a specific topic with string values.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or the topic type defined in the specification is incompatible with string (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).

- (PTDiffusionStringUpdateStream *) stringUpdateStreamWithPath: (NSString *)  path
specification: (PTDiffusionTopicSpecification *)  specification
constraint: (PTDiffusionUpdateConstraint *)  constraint 

Creates an update stream to use for creating and updating a specific topic with string values if a constraint is satisfied.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required update streams should be used with session locks as constraints.

Streams are validated lazily when the first 'set' or 'validate' operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

Parameters
pathThe path of the topic.
specificationThe required specification of the topic.
constraintThe constraint that must be satisfied for the update stream to be validated.
Returns
An update stream.
Exceptions
NSInvalidArgumentExceptionIf any argument is nil or the topic type defined in the specification is incompatible with string (PTDiffusionDataTypes).
Since
6.3

Provided by category PTDiffusionTopicUpdateFeature(PTDiffusionPrimitive).