Diffusion C API  6.7.4
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Maintaining topic state.

Functions

void diffusion_topic_update_set (SESSION_T *session, DIFFUSION_TOPIC_UPDATE_SET_PARAMS_T params)
 Sets the topic to a specified value. More...
 
void diffusion_topic_update_set_with_constraint (SESSION_T *session, const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *constraint, DIFFUSION_TOPIC_UPDATE_SET_PARAMS_T params)
 Sets the topic to a specified value. More...
 
void diffusion_topic_update_add_and_set (SESSION_T *session, DIFFUSION_TOPIC_UPDATE_ADD_AND_SET_PARAMS_T params)
 Sets the topic to a specified value. More...
 
void diffusion_topic_update_add_and_set_with_constraint (SESSION_T *session, const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *constraint, DIFFUSION_TOPIC_UPDATE_ADD_AND_SET_PARAMS_T params)
 Sets the topic to a specified value. More...
 
bool diffusion_apply_json_patch (SESSION_T *session, DIFFUSION_APPLY_JSON_PATCH_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
 Applies a JSON Patch to a JSON topic. More...
 
bool diffusion_apply_json_patch_with_constraint (SESSION_T *session, const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *constraint, DIFFUSION_APPLY_JSON_PATCH_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
 Applies a JSON Patch to a JSON topic. More...
 
DIFFUSION_TOPIC_UPDATE_STREAM_Tdiffusion_topic_update_create_update_stream (SESSION_T *session, const char *topic_path, DIFFUSION_DATATYPE datatype)
 Creates an update strean to use for updating a specific topic. More...
 
DIFFUSION_TOPIC_UPDATE_STREAM_Tdiffusion_topic_update_create_update_stream_with_constraint (SESSION_T *session, const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *constraint, const char *topic_path, DIFFUSION_DATATYPE datatype)
 Creates an update stream to use for updating a specific topic. More...
 
DIFFUSION_TOPIC_UPDATE_STREAM_Tdiffusion_topic_update_create_update_stream_adding_topic (SESSION_T *session, const char *topic_path, const TOPIC_SPECIFICATION_T *specification, DIFFUSION_DATATYPE datatype, DIFFUSION_TOPIC_UPDATE_STREAM_PARAMS_T params)
 Creates an update stream to use for creating and updating a specific topic. More...
 
DIFFUSION_TOPIC_UPDATE_STREAM_Tdiffusion_topic_update_create_update_stream_adding_topic_with_constraint (SESSION_T *session, const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *constraint, const char *topic_path, const TOPIC_SPECIFICATION_T *specification, DIFFUSION_DATATYPE datatype, DIFFUSION_TOPIC_UPDATE_STREAM_PARAMS_T params)
 Creates an update stream to use for creating and updating a specific topic. More...
 

Detailed Description

Function Documentation

bool diffusion_apply_json_patch ( SESSION_T session,
DIFFUSION_APPLY_JSON_PATCH_PARAMS_T  params,
DIFFUSION_API_ERROR api_error 
)

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

If the patch is not a valid JSON patch, DIFF_ERR_INVALID_PATCH will be the error code called to error callback. If the patch contains invalid CBOR, DIFF_ERR_FAILED_PATCH will be the error code instead.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
paramsParameters describing a JSON patch application request and callbacks handlers which may be invoked in response.
api_errorPopulated on API error. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_apply_json_patch_with_constraint ( SESSION_T session,
const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T constraint,
DIFFUSION_APPLY_JSON_PATCH_PARAMS_T  params,
DIFFUSION_API_ERROR api_error 
)

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 diffusion_apply_json_patch.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
constraintThe constraint that must be satisfied for the patch to be applied
paramsParameters describing a JSON patch application request and callbacks handlers which may be invoked in response.
api_errorPopulated on API error. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
void diffusion_topic_update_add_and_set ( SESSION_T session,
DIFFUSION_TOPIC_UPDATE_ADD_AND_SET_PARAMS_T  params 
)

Sets the topic to a specified value.

If a topic does not exist at params.topic_path, one will be created using the params.specification. If a topic does exist, its specification must match params.specification, otherwise the operation will fail with an error dispatched to params.on_error, if non NULL.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
paramsParameters describing a topic add and set request and callbacks handlers which may be invoked in response.
void diffusion_topic_update_add_and_set_with_constraint ( SESSION_T session,
const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T constraint,
DIFFUSION_TOPIC_UPDATE_ADD_AND_SET_PARAMS_T  params 
)

Sets the topic to a specified value.

If a topic does not exist at params.topic_path, one will be created using the params.specification. If a topic does exist, its specification must match params.specification, otherwise the operation will fail with an error dispatched to params.on_error, if non NULL.

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

In other respects it works in the same way as diffusion_topic_update_set

Parameters
sessionThe session handle. If NULL, this function returns immediately.
constraintThe conditional constraint to be applied to topic add and set operation
paramsParameters describing a topic add and set request and callbacks handlers which may be invoked in response.
DIFFUSION_TOPIC_UPDATE_STREAM_T* diffusion_topic_update_create_update_stream ( SESSION_T session,
const char *  topic_path,
DIFFUSION_DATATYPE  datatype 
)

Creates an update strean to use for updating a specific topic.

The type of the topic being updated must match the dataype from the params.datatype parameter.

Update streams send a sequence of updates for a specific topic. They take advantage of the sending a sequence of updates to generate and send binary deltas to the server. 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 diffusion_topic_update_stream_set is operation is completed. Once validated a stream can be invalidated, after which it rejects future updates.

diffusion_topic_update_stream_free should be called on this pointer when no longer needed.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
topic_pathThe path of the topic
datatypeThe topic's datatype
Returns
a memory allocated diffusion topic update stream
DIFFUSION_TOPIC_UPDATE_STREAM_T* diffusion_topic_update_create_update_stream_adding_topic ( SESSION_T session,
const char *  topic_path,
const TOPIC_SPECIFICATION_T specification,
DIFFUSION_DATATYPE  datatype,
DIFFUSION_TOPIC_UPDATE_STREAM_PARAMS_T  params 
)

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

If a topic does exist, its specification must match specification, otherwise the operation will fail with DIFF_ERR_INCOMPATIBLE_TOPIC being called to the error callback

In other respects this method works in the same way as diffusion_topic_update_create_update_stream.

diffusion_topic_update_stream_free should be called on this pointer when no longer needed.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
topic_pathThe topic path
specificationThe topic's specification
datatypeThe topic's datatype
paramsParameters describing a request to create an update stream
Returns
a memory allocated diffusion topic update stream
DIFFUSION_TOPIC_UPDATE_STREAM_T* diffusion_topic_update_create_update_stream_adding_topic_with_constraint ( SESSION_T session,
const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T constraint,
const char *  topic_path,
const TOPIC_SPECIFICATION_T specification,
DIFFUSION_DATATYPE  datatype,
DIFFUSION_TOPIC_UPDATE_STREAM_PARAMS_T  params 
)

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

If a topic does exist, its specification must match specification, otherwise the operation will fail with DIFF_ERR_INCOMPATIBLE_TOPIC being called to the error callback.

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

In other respects this method works in the same way as diffusion_topic_update_create_update_stream.

diffusion_topic_update_stream_free should be called on this pointer when no longer needed.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
constraintThe constraint that must be satisfied for the update stream to be validated
topic_pathThe topic path
specificationThe topic's specification
datatypeThe topic's datatype
paramsParameters describing a request to create an update stream
Returns
a memory allocated diffusion topic update stream
DIFFUSION_TOPIC_UPDATE_STREAM_T* diffusion_topic_update_create_update_stream_with_constraint ( SESSION_T session,
const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T constraint,
const char *  topic_path,
DIFFUSION_DATATYPE  datatype 
)

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

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

In other respects it works in the same way as diffusion_topic_update_create_update_stream.

diffusion_topic_update_stream_free should be called on this pointer when no longer needed.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
constraintThe constraint that must be satisfied for the update stream to be validated
topic_pathThe path of the topic
datatypeThe topic's datatype
Returns
a memory allocated diffusion topic update stream
void diffusion_topic_update_set ( SESSION_T session,
DIFFUSION_TOPIC_UPDATE_SET_PARAMS_T  params 
)

Sets the topic to a specified value.

The NULL value can only be passed to the params.update property when updating DATATYPE_STRING,DATATYPE_INT64 or DATATYPE_DOUBLE topics.

When a topic of type TOPIC_TYPE_STRING, TOPIC_TYPE_INT64 or TOPIC_TYPE_DOUBLE is set to null, 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 null. New subscribers will not receive a value notification.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
paramsParameters describing a topic update set request and callbacks handlers which may be invoked in response.
void diffusion_topic_update_set_with_constraint ( SESSION_T session,
const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T constraint,
DIFFUSION_TOPIC_UPDATE_SET_PARAMS_T  params 
)

Sets the topic to a specified value.

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

In other respects it works in the same way as diffusion_topic_update_set

Parameters
sessionThe session handle. If NULL, this function returns immediately.
constraintThe conditional constraint to be applied to topic update set operation
paramsParameters describing a topic update set request and callbacks handlers which may be invoked in response.