Diffusion C API  6.4.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
update-constraint.h File Reference

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.
 

Functions

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_Tdiffusion_topic_update_constraint_locked (const DIFFUSION_SESSION_LOCK_T *lock)
 Create a constraint requiring a lock to be held by the session. More...
 
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_Tdiffusion_topic_update_constraint_value (const BUF_T *value)
 Create a constraint requiring the current value of the topic to match the supplied value. More...
 
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_Tdiffusion_topic_update_constraint_no_value (void)
 Create a constraint requiring the topic to have no value. More...
 
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_Tdiffusion_topic_update_constraint_no_topic (void)
 Create a constraint requiring the path to have no topic. More...
 
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_Tdiffusion_topic_update_constraint_partial_json_with_value (const char *pointer, DIFFUSION_DATATYPE datatype, const BUF_T *value)
 Require a value at a specific position in the JSON object. More...
 
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_Tdiffusion_topic_update_constraint_partial_json_without_value (const char *pointer)
 Require a specific position in the JSON object to be absent. More...
 
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_Tdiffusion_topic_update_constraint_and (const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *constraint, const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *other_constraint)
 Create a composed constraint that represents a logical AND of two constraints. More...
 
void diffusion_topic_update_constraint_free (DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *constraint)
 Free a memory allocated DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T More...
 

Detailed Description

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:

  • active session locks
  • existence of the topic
  • current value of the topic

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.

Function Documentation

DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T* diffusion_topic_update_constraint_and ( const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T constraint,
const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T other_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.

Parameters
constrainta constraint that will be logically-ANDed with other_constraint
other_constrainta constraint that will be logically-ANDed with constraint
Returns
a composed constraint that represents a logical AND of constraint and other_constraint
void diffusion_topic_update_constraint_free ( DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T constraint)

Free a memory allocated DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T

Parameters
constraintthe 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.

Parameters
lockthe lock
Returns
the constraint
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T* diffusion_topic_update_constraint_no_topic ( void  )

Create a constraint requiring the path to have no topic.

This can be used set 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.

Returns
the constraint
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T* diffusion_topic_update_constraint_no_value ( void  )

Create a constraint requiring the topic to have no value.

This can be used set 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.

Returns
the constraint
DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T* diffusion_topic_update_constraint_partial_json_with_value ( const char *  pointer,
DIFFUSION_DATATYPE  datatype,
const BUF_T value 
)

Require a value at a specific position in the JSON object.

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.

Parameters
pointerthe pointer expression
datatypethe value datatype
valuethe value
Returns
the constraint. 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.

Parameters
pointerthe pointer expression
Returns
the constraint. NULL if pointer is NULL
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 match the supplied value.

NULL value cannot be passed as a parameter because it would prevent the required topic type being inferred.

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.

Parameters
valuethe value
Returns
the constraint