Access to the Webcom database and be notified of data changes

Typedefs
typedef void *	on_handle_t
typedef int(*	on_callback_f) (wc_context_t *ctx, on_handle_t handle, char *data, char *current_key, char *previous_key)

Enumerations
enum	on_event_type { ON_CHILD_ADDED, ON_CHILD_REMOVED, ON_CHILD_CHANGED, ON_VALUE }

Functions
on_handle_t	wc_datasync_on_value (wc_context_t *ctx, char *path, on_callback_f callback)
on_handle_t	wc_datasync_on_child_added (wc_context_t *ctx, char *path, on_callback_f callback)
on_handle_t	wc_datasync_on_child_changed (wc_context_t *ctx, char *path, on_callback_f callback)
on_handle_t	wc_datasync_on_child_removed (wc_context_t *ctx, char *path, on_callback_f callback)
char *	wc_datasync_on_handle_get_path (on_handle_t h)
wc_context_t *	wc_datasync_on_handle_get_ctx (on_handle_t h)
void	wc_datasync_off (on_handle_t h)
void	wc_datasync_off_path (wc_context_t *ctx, char *path)
void	wc_datasync_off_path_type (wc_context_t *ctx, char *path, enum on_event_type type)

Detailed Description

This set of functions is dedicated to registering callbacks on specific data events occurring on the Webcom datasync tree:

• a given path has changed,
• a child was added on a given path,
• a child was modified on a given path,
• a child was removed on a given path.

The wc_datasync_on_XXX() functions all return an opaque handle that represents the subscription. This handle can be used to cancel such a subscription, or to get some informations associated to it such as the data path it refers to, or the Webcom context it is associated to.

Typedef Documentation

on_callback_f

typedef int(* on_callback_f) (wc_context_t *ctx, on_handle_t handle, char *data, char *current_key, char *previous_key)

Callback type for data events registered by the wc_datasync_on_XXX() functions.

Parameters

ctx	the webcom context
handle	the handle of the registration that triggered this callback
data	a JSON string containing the current data at the registration's path
current_key	contains the name of the current key for a ON_CHILD_XXX event, NULL for ON_VALUE events
previous_key	contains the name of the previous sibling key for a ON_CHILD_XXX event, NULL if it is the first sibling or for ON_VALUE events

Returns

return 1 to keep this registration active, 0 to cancel it

on_handle_t

typedef void* on_handle_t

Opaque type that represents a subscription

Enumeration Type Documentation

on_event_type

enum on_event_type

Enumerator
ON_CHILD_ADDED
ON_CHILD_REMOVED
ON_CHILD_CHANGED
ON_VALUE

Function Documentation

wc_datasync_off()

void wc_datasync_off

(

on_handle_t

h

)

Unsubscribes and deletes a subscription

Parameters

h	the subscription handle

Warning

Do not use this function inside a on_XXX callback, it will lead to undefined behavior and most likely a crash. Return 0 from the callback if you wish to cancel this callback.

wc_datasync_off_path()

void wc_datasync_off_path	(	wc_context_t *	ctx,
		char *	path
	)

Unsubscribes and deletes all subscriptions for a given path

Parameters

ctx	the webcom context
path	the path

Warning

Do not use this function inside a on_XXX callback, it will lead to undefined behavior and most likely a crash.

wc_datasync_off_path_type()

void wc_datasync_off_path_type	(	wc_context_t *	ctx,
		char *	path,
		enum on_event_type	type
	)

Unsubscribes and deletes all subscriptions aof a given type for a given path

Parameters

ctx	the webcom context
path	the path
type	the type

Warning

Do not use this function inside a on_XXX callback, it will lead to undefined behavior and most likely a crash.

wc_datasync_on_child_added()

on_handle_t wc_datasync_on_child_added	(	wc_context_t *	ctx,
		char *	path,
		on_callback_f	callback
	)

Registers a callback to monitor the apparition of a new key at the given node (path). When this method is called, the callback will be called once for every already existing key at the given path, and will be called again each time a new key is added at this path.

Parameters

ctx	the Webcom context
path	the path
callback	the callback

Returns

the subscription handle

wc_datasync_on_child_changed()

on_handle_t wc_datasync_on_child_changed	(	wc_context_t *	ctx,
		char *	path,
		on_callback_f	callback
	)

Registers a callback to monitor the modification of a child element of the given path. The callback will be called each time a child node changes at the given path, except when it's an addition or a deletion.

Parameters

ctx	the Webcom context
path	the path
callback	the callback

Returns

the subscription handle

wc_datasync_on_child_removed()

on_handle_t wc_datasync_on_child_removed	(	wc_context_t *	ctx,
		char *	path,
		on_callback_f	callback
	)

Registers a callback to monitor the deletion of a child element of the given path. The callback will be called each time a child node is removed at the given path.

Parameters

ctx	the Webcom context
path	the path
callback	the callback

Returns

the subscription handle

wc_datasync_on_handle_get_ctx()

wc_context_t* wc_datasync_on_handle_get_ctx

(

on_handle_t

h

)

Gets the context associated to a subscription handle

Parameters

h	the handle

Returns

the context

wc_datasync_on_handle_get_path()

char* wc_datasync_on_handle_get_path

(

on_handle_t

h

)

Gets the path associated to a subscription handle

Parameters

h	the handle

Returns

the path

wc_datasync_on_value()

on_handle_t wc_datasync_on_value	(	wc_context_t *	ctx,
		char *	path,
		on_callback_f	callback
	)

Registers a callback to monitor any change in the data under the given path. When this method is called, the callback will be called once with the current value of the database at the given path, and will be called again each time a change occurs at this path.

Parameters

ctx	the Webcom context
path	the path
callback	the callback

Returns

the subscription handle