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

Detailed Description

Function Documentation

diffusion_apply_json_patch()

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

session	The session handle. If NULL, this function returns immediately.
params	Parameters describing a JSON patch application request and callbacks handlers which may be invoked in response.
api_error	Populated 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.

diffusion_apply_json_patch_with_constraint()

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

session	The session handle. If NULL, this function returns immediately.
constraint	The constraint that must be satisfied for the patch to be applied
params	Parameters describing a JSON patch application request and callbacks handlers which may be invoked in response.
api_error	Populated 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.

diffusion_topic_update_add_and_set()

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

session	The session handle. If NULL, this function returns immediately.
params	Parameters describing a topic add and set request and callbacks handlers which may be invoked in response.

diffusion_topic_update_add_and_set_with_constraint()

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

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

diffusion_topic_update_set()

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

session	The session handle. If NULL, this function returns immediately.
params	Parameters describing a topic update set request and callbacks handlers which may be invoked in response.

diffusion_topic_update_set_with_constraint()

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

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