golioth_lightdb_state

Functions
enum golioth_status	golioth_lightdb_set_int (struct golioth_client *client, const char *path, int32_t value, golioth_set_cb_fn callback, void *callback_arg)
enum golioth_status	golioth_lightdb_set_bool (struct golioth_client *client, const char *path, bool value, golioth_set_cb_fn callback, void *callback_arg)
enum golioth_status	golioth_lightdb_set_float (struct golioth_client *client, const char *path, float value, golioth_set_cb_fn callback, void *callback_arg)
enum golioth_status	golioth_lightdb_set_string (struct golioth_client *client, const char *path, const char *str, size_t str_len, golioth_set_cb_fn callback, void *callback_arg)
enum golioth_status	golioth_lightdb_set (struct golioth_client *client, const char *path, enum golioth_content_type content_type, const uint8_t *buf, size_t buf_len, golioth_set_cb_fn callback, void *callback_arg)
enum golioth_status	golioth_lightdb_get (struct golioth_client *client, const char *path, enum golioth_content_type content_type, golioth_get_cb_fn callback, void *callback_arg)
enum golioth_status	golioth_lightdb_delete (struct golioth_client *client, const char *path, golioth_set_cb_fn callback, void *callback_arg)
enum golioth_status	golioth_lightdb_observe (struct golioth_client *client, const char *path, enum golioth_content_type content_type, golioth_get_cb_fn callback, void *callback_arg)

Detailed Description

Functions for interacting with Golioth LightDB State service.

https://docs.golioth.io/reference/protocols/coap/lightdb

Function Documentation

golioth_lightdb_delete()

enum golioth_status golioth_lightdb_delete	(	struct golioth_client *	client,
		const char *	path,
		golioth_set_cb_fn	callback,
		void *	callback_arg )

Delete a path in LightDB state

This function will enqueue a request and return immediately without waiting for a response from the server. The callback will be invoked when a response is received or a timeout occurs.

Note: the server responds with success even if the path does not exist in LightDB state.

Parameters

client	The client handle from golioth_client_create
path	The path in LightDB state to delete (e.g. "my_integer")
callback	Callback to call on response received or timeout. Can be NULL.
callback_arg	Callback argument, passed directly when callback invoked. Can be NULL.

Return values

GOLIOTH_OK	request enqueued
GOLIOTH_ERR_NULL	invalid client handle
GOLIOTH_ERR_INVALID_STATE	client is not running, currently stopped
GOLIOTH_ERR_MEM_ALLOC	memory allocation error
GOLIOTH_ERR_QUEUE_FULL	request queue is full, this request is dropped

golioth_lightdb_get()

enum golioth_status golioth_lightdb_get	(	struct golioth_client *	client,
		const char *	path,
		enum golioth_content_type	content_type,
		golioth_get_cb_fn	callback,
		void *	callback_arg )

Get data in LightDB state at a particular path

This function will enqueue a request and return immediately without waiting for a response from the server. The callback will be invoked when a response is received or a timeout occurs.

The data passed into the callback function will be the raw payload bytes from the server response. The callback function can convert the payload to the appropriate type using, e.g. golioth_payload_as_int, or using a parsing library (like cJSON or zCBOR) in the case of a serialized object payload

Parameters

client	The client handle from golioth_client_create
path	The path in LightDB state to get (e.g. "my_integer")
content_type	The serialization format to request for the path
callback	Callback to call on response received or timeout. Can be NULL.
callback_arg	Callback argument, passed directly when callback invoked. Can be NULL.

golioth_lightdb_observe()

enum golioth_status golioth_lightdb_observe	(	struct golioth_client *	client,
		const char *	path,
		enum golioth_content_type	content_type,
		golioth_get_cb_fn	callback,
		void *	callback_arg )

Observe a path in LightDB state

Observations allow the Golioth server to notify clients of a change in data at a particular path, without the client having to poll for changes.

This function will enqueue a request and return immediately without waiting for a response from the server. The callback will be invoked whenever the data at path changes.

The data passed into the callback function will be the raw payload bytes from the server. The callback function can convert the payload to the appropriate type using, e.g. golioth_payload_as_int, or using a JSON parsing library (like cJSON) in the case of JSON payload.

Parameters

client	The client handle from golioth_client_create
path	The path in LightDB state to observe (e.g. "my_integer")
content_type	The serialization format to request for the path
callback	Callback to call on response received or timeout. Can be NULL.
callback_arg	Callback argument, passed directly when callback invoked. Can be NULL.

Return values

GOLIOTH_OK	request enqueued
GOLIOTH_ERR_NULL	invalid client handle
GOLIOTH_ERR_INVALID_STATE	client is not running, currently stopped
GOLIOTH_ERR_MEM_ALLOC	memory allocation error
GOLIOTH_ERR_QUEUE_FULL	request queue is full, this request is dropped

golioth_lightdb_set()

enum golioth_status golioth_lightdb_set	(	struct golioth_client *	client,
		const char *	path,
		enum golioth_content_type	content_type,
		const uint8_t *	buf,
		size_t	buf_len,
		golioth_set_cb_fn	callback,
		void *	callback_arg )

Set an object in LightDB state at a particular path

The serialization format of the object is specified by the content_type argument. Currently this is either JSON or CBOR.

Similar to golioth_lightdb_set_int.

Parameters

client	The client handle from golioth_client_create
path	The path in LightDB state to set (e.g. "my_integer")
content_type	The serialization format of buf
buf	A buffer containing the object to send
buf_len	Length of buf
callback	Callback to call on response received or timeout. Can be NULL.
callback_arg	Callback argument, passed directly when callback invoked. Can be NULL.

Return values

GOLIOTH_OK	request enqueued
GOLIOTH_ERR_NULL	invalid client handle
GOLIOTH_ERR_INVALID_STATE	client is not running, currently stopped
GOLIOTH_ERR_MEM_ALLOC	memory allocation error
GOLIOTH_ERR_QUEUE_FULL	request queue is full, this request is dropped

golioth_lightdb_set_bool()

enum golioth_status golioth_lightdb_set_bool	(	struct golioth_client *	client,
		const char *	path,
		bool	value,
		golioth_set_cb_fn	callback,
		void *	callback_arg )

Set a bool in LightDB state at a particular path

Same as golioth_lightdb_set_int, but for type bool

golioth_lightdb_set_float()

enum golioth_status golioth_lightdb_set_float	(	struct golioth_client *	client,
		const char *	path,
		float	value,
		golioth_set_cb_fn	callback,
		void *	callback_arg )

Set a float in LightDB state at a particular path

Same as golioth_lightdb_set_int, but for type float

golioth_lightdb_set_int()

enum golioth_status golioth_lightdb_set_int	(	struct golioth_client *	client,
		const char *	path,
		int32_t	value,
		golioth_set_cb_fn	callback,
		void *	callback_arg )

Set an integer in LightDB state at a particular path

This function will enqueue a request and return immediately without waiting for a response from the server. Optionally, the user may supply a callback that will be called when the response is received (indicating the request was acknowledged by the server) or a timeout occurs (response never received).

Parameters

client	The client handle from golioth_client_create
path	The path in LightDB state to set (e.g. "my_integer")
value	The value to set at path
callback	Callback to call on response received or timeout. Can be NULL.
callback_arg	Callback argument, passed directly when callback invoked. Can be NULL.

Return values

GOLIOTH_OK	request enqueued
GOLIOTH_ERR_NULL	invalid client handle
GOLIOTH_ERR_INVALID_STATE	client is not running, currently stopped
GOLIOTH_ERR_MEM_ALLOC	memory allocation error
GOLIOTH_ERR_QUEUE_FULL	request queue is full, this request is dropped

golioth_lightdb_set_string()

enum golioth_status golioth_lightdb_set_string	(	struct golioth_client *	client,
		const char *	path,
		const char *	str,
		size_t	str_len,
		golioth_set_cb_fn	callback,
		void *	callback_arg )

Set a string in LightDB state at a particular path

Same as golioth_lightdb_set_int, but for type string