 |
Diffusion C API
6.10.4
|
|
Diffusion C API
6.10.4
|
A constraint to be applied to an update operation or the creation of an update stream. More...
Typedefs | |
|
typedef struct DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T | DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T |
| Opaque topic update constraint struct. | |
A constraint to be applied to an update operation or the creation of an update stream.
Constraints describe a condition that must be satisfied for an operation to succeed. Constraints can be applied to the setting of a value or creation of an update stream. Constraints are only evaluated on the server.
The constraints are evaluated using the:
The value of a topic can be described in several ways. The value can be described as an exact value, a partial value or an unset value.
Constraints can be composed with one another. It is only possible to construct logical ANDs of constraints. Constraints can only be composed if the resulting constraint is satisfiable. Multiple session locks can be held but a topic can only have a single value. Constraints specifying multiple topic values cannot be constructed.
An operator used in a constraint comparison.
| DEPRECATED | ( | DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * | diffusion_topic_update_constraint_partial_json_with_valueconst char *pointer, DIFFUSION_DATATYPE datatype, const BUF_T *value | ) |
Require a value at a specific position in the JSON object.
This is equivalent to calling diffusion_topic_update_constraint_partial_json_value_comparison with an operator of DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_IS.
The pointer is a JSON Pointer syntax reference locating the value in the JSON object.
Only string, int64, and double values are supported. The null value may be passed for any type.
diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.
| pointer | the pointer expression |
| datatype | the value datatype |
| value | the value |
NULL if datatype isn't one of DATATYPE_STRING, DATATYPE_INT64 or DATATYPE_DOUBLE. Also NULL if pointer is NULL.diffusion_topic_update_constraint_partial_json_value_comparison method with the DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_IS operator. | DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T* diffusion_topic_update_constraint_and | ( | const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * | left_constraint, |
| const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * | right_constraint | ||
| ) |
Create a composed constraint that represents a logical AND of two constraints.
diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.
| left_constraint | a constraint that will be logically-ANDed with right_constraint |
| right_constraint | a constraint that will be logically-ANDed with left_constraint |
left_constraint and right_constraint | void diffusion_topic_update_constraint_free | ( | DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * | constraint | ) |
Free a memory allocated DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T
| constraint | the constraint to be freed |
| DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T* diffusion_topic_update_constraint_locked | ( | const DIFFUSION_SESSION_LOCK_T * | lock | ) |
Create a constraint requiring a lock to be held by the session.
This can be used to co-ordination operations between multiple sessions.
diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.
| lock | the lock |
| DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T* diffusion_topic_update_constraint_no_topic | ( | void | ) |
Create a constraint requiring the path to have no topic.
This is useful when setting the first value of a topic being added using diffusion_topic_update_add_and_set without changing the value if the topic already exists. This constraint is unsatisfied if a topic is present at the path, making it unsuitable for operations that try to set topics without adding them.
diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.
| DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T* diffusion_topic_update_constraint_no_value | ( | void | ) |
Create a constraint requiring the topic to have no value.
This is useful when setting the first value of a topic. This constraint is unsatisfied if no topic is present at the path, making it unsuitable for operations that try to add topics.
diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.
| DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T* diffusion_topic_update_constraint_or | ( | const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * | left_constraint, |
| const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T * | right_constraint | ||
| ) |
Create a composed constraint that represents a logical OR of two constraints.
diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.
| left_constraint | a constraint that will be logically-ORed with right_constraint |
| right_constraint | a constraint that will be logically-ORed with left_constraint |
left_constraint and right_constraint| DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T* diffusion_topic_update_constraint_partial_json_comparison | ( | const char * | pointer, |
| DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_T | comparison_operator, | ||
| DIFFUSION_UPDATE_CONSTRAINT_VALUE_T * | value | ||
| ) |
Compares a location within the JSON topic value to a specified value.
If there is no value found at the specified pointer position, the constraint will be unsatisfied.
If a String value is supplied and the operator is EQ or NE, the string representation of the topic value at the given pointer will be compared to the supplied value. If the value at the pointer position is not a string or number the constraint will be unsatisfied. Other operators (other than IS) are not permitted with String values.
If a number value (Integer, Long or Double) is supplied the value will be compared with the number value at the topic location. This will work with JSON string or number values only. JSON strings can only be compared if they contain a value that can be parsed as a number. If a string value at the location cannot be parsed as a number, the constraint will be unsatisfied. Any of the operators (other than IS) can be used with such number comparisons.
Decimal numbers can be compared with integral numbers so 1 is equal to 1.0, "1", or "1.0".
If a NULL value is supplied and the operator is EQ or NE, the topic value at the given pointer will be compared to JSON null. Other operators (other than IS) are not permitted with a NULL value.
If a Boolean value is supplied and the operator is EQ, the topic value at the given pointer will be compared to the boolean value. Other operators are not permitted with a boolean value.
If the IS operator is specified the supplied value will be compared to the topic value for strict binary equality. In this case the value must be of type String, Integer, Long, Double, Bytes, or NULL. This is slightly more efficient than the lenient comparisons described above.
| pointer | the pointer expression |
| comparison_operator | the operator that determines the type of comparison |
| value_type | the value datatype |
| value | the value |
NULL if datatype isn't one of DATATYPE_STRING, DATATYPE_INT64 or DATATYPE_DOUBLE. Also NULL if pointer is NULL.| DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T* diffusion_topic_update_constraint_partial_json_without_value | ( | const char * | pointer | ) |
Require a specific position in the JSON object to be absent.
This does not match positions that have null values.
The pointer is a JSON Pointer syntax reference that should have no value in the JSON object.
diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.
| pointer | the pointer expression |
NULL if pointer is NULL | DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T* diffusion_topic_update_constraint_unconstrained | ( | void | ) |
Create a constraint with no requirements.
This constraint is always satisfied.
diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.
| DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T* diffusion_topic_update_constraint_value | ( | const BUF_T * | value | ) |
Create a constraint requiring the current value of the topic to exactly match the supplied value.
NULL value cannot be passed as a parameter because it would prevent the required topic type being inferred.
This is exactly equivalent to calling diffusion_topic_update_constraint_value_comparison(DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_IS, value).
This can be used to change the value of a topic. This constraint is unsatisfied if no topic is present at the path making it unsuitable for operations that try to add topics.
diffusion_topic_update_constraint_free should be called on the pointer when no longer needed.
| value | the value |
| DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T* diffusion_topic_update_constraint_value_comparison | ( | DIFFUSION_TOPIC_UPDATE_CONSTRAINT_OPERATOR_T | comparison_operator, |
| DIFFUSION_UPDATE_CONSTRAINT_VALUE_T * | value | ||
| ) |
Create a constraint comparing the current value of a topic to a supplied value.
If a String value is supplied and the operator is EQ or NE, the string representation of the topic will be compared to the supplied value. This can only be used with primitive topic types (or TIME_SERIES topics with a primitive event type). Other operators (other than IS) are not permitted with String values.
If a number value is supplied (Integer, Long or Double), the value will be compared with the number value of the topic. This will work with STRING,INT64 or DOUBLE topics (or TIME_SERIES topics with a primitive event type) only. STRING topics can only be compared if they contain a value that can be parsed as a number.
If the value of a STRING topic cannot be parsed as a number, or the topic is of any other non-number type the constraint will be unsatisfied. Any of the operators (other than IS) can be used with such number comparisons. Decimal numbers can be compared with integral numbers so 1 is equal to 1.0, "1", or "1.0".
If the IS operator is specified, the specified value will be compared to the topic value for strict binary equality.
The value type can be any value type supported by DataTypes (Integer is allowed and is treated as a Long) or any Bytes value and can be used to compare against any topic type.
When a STRING, INT64 or DOUBLE topic is updated to a NULL value, the topic is set to have no value.
Use the diffusion_topic_update_constraint_no_value() constraint to check if the topic has no value. This constraint is useful when changing the value of a topic. This constraint is unsatisfied if no topic is present at the path, making it unsuitable for operations that try to add topics.
| comparison_operator | the operator the determines the type of comparison |
| value | the value |
1.8.5