golioth_lightdb_state

Functions
enum golioth_status	golioth_lightdb_set_int_async (struct golioth_client *client, const char *path, int32_t value, golioth_set_cb_fn callback, void *callback_arg)
enum golioth_status	golioth_lightdb_set_int_sync (struct golioth_client *client, const char *path, int32_t value, int32_t timeout_s)
enum golioth_status	golioth_lightdb_set_bool_async (struct golioth_client *client, const char *path, bool value, golioth_set_cb_fn callback, void *callback_arg)
enum golioth_status	golioth_lightdb_set_bool_sync (struct golioth_client *client, const char *path, bool value, int32_t timeout_s)
enum golioth_status	golioth_lightdb_set_float_async (struct golioth_client *client, const char *path, float value, golioth_set_cb_fn callback, void *callback_arg)
enum golioth_status	golioth_lightdb_set_float_sync (struct golioth_client *client, const char *path, float value, int32_t timeout_s)
enum golioth_status	golioth_lightdb_set_string_async (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_string_sync (struct golioth_client *client, const char *path, const char *str, size_t str_len, int32_t timeout_s)
enum golioth_status	golioth_lightdb_set_async (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_set_sync (struct golioth_client *client, const char *path, enum golioth_content_type content_type, const uint8_t *buf, size_t buf_len, int32_t timeout_s)
enum golioth_status	golioth_lightdb_get_async (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_get_int_sync (struct golioth_client *client, const char *path, int32_t *value, int32_t timeout_s)
enum golioth_status	golioth_lightdb_get_bool_sync (struct golioth_client *client, const char *path, bool *value, int32_t timeout_s)
	Similar to golioth_lightdb_get_int_sync, but for type bool.
enum golioth_status	golioth_lightdb_get_float_sync (struct golioth_client *client, const char *path, float *value, int32_t timeout_s)
	Similar to golioth_lightdb_get_int_sync, but for type float.
enum golioth_status	golioth_lightdb_get_string_sync (struct golioth_client *client, const char *path, char *strbuf, size_t strbuf_size, int32_t timeout_s)
	Similar to golioth_lightdb_get_int_sync, but for type string.
enum golioth_status	golioth_lightdb_get_sync (struct golioth_client *client, const char *path, enum golioth_content_type content_type, uint8_t *buf, size_t *buf_size, int32_t timeout_s)
	Similar to golioth_lightdb_get_int_sync, but for objects.
enum golioth_status	golioth_lightdb_delete_async (struct golioth_client *client, const char *path, golioth_set_cb_fn callback, void *callback_arg)
enum golioth_status	golioth_lightdb_delete_sync (struct golioth_client *client, const char *path, int32_t timeout_s)
enum golioth_status	golioth_lightdb_observe_async (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_async()

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

Delete a path in LightDB state asynchronously

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_delete_sync()

enum golioth_status golioth_lightdb_delete_sync	(	struct golioth_client *	client,
		const char *	path,
		int32_t	timeout_s )

Delete a path in LightDB state synchronously

This function will block until one of three things happen (whichever comes first):

1. A response is received from the server
2. The user-provided timeout_s period expires without receiving a response
3. The default GOLIOTH_COAP_RESPONSE_TIMEOUT_S period expires without receiving a response

Parameters

client	The client handle from golioth_client_create
path	The path in LightDB state to delete (e.g. "my_integer")
timeout_s	The timeout, in seconds, for receiving a server response

Return values

GOLIOTH_OK	response received from server, set was successful
GOLIOTH_ERR_NULL	invalid client handle
GOLIOTH_ERR_INVALID_STATE	client is not running, currently stopped
GOLIOTH_ERR_QUEUE_FULL	request queue is full, this request is dropped
GOLIOTH_ERR_TIMEOUT	response not received from server, timeout occurred

golioth_lightdb_get_async()

enum golioth_status golioth_lightdb_get_async	(	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 asynchronously.

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_get_bool_sync()

enum golioth_status golioth_lightdb_get_bool_sync	(	struct golioth_client *	client,
		const char *	path,
		bool *	value,
		int32_t	timeout_s )

Similar to golioth_lightdb_get_int_sync, but for type bool.

golioth_lightdb_get_float_sync()

enum golioth_status golioth_lightdb_get_float_sync	(	struct golioth_client *	client,
		const char *	path,
		float *	value,
		int32_t	timeout_s )

Similar to golioth_lightdb_get_int_sync, but for type float.

golioth_lightdb_get_int_sync()

enum golioth_status golioth_lightdb_get_int_sync	(	struct golioth_client *	client,
		const char *	path,
		int32_t *	value,
		int32_t	timeout_s )

Get an integer in LightDB state at a particular path synchronously.

This function will block until one of three things happen (whichever comes first):

1. A response is received from the server
2. The user-provided timeout_s period expires without receiving a response
3. The default GOLIOTH_COAP_RESPONSE_TIMEOUT_S period expires without receiving a response

Parameters

client	The client handle from golioth_client_create
path	The path in LightDB state to get (e.g. "my_integer")
value	Output parameter, memory allocated by caller, populated with value of integer
timeout_s	The timeout, in seconds, for receiving a server response

Return values

GOLIOTH_OK	response received from server, set was successful
GOLIOTH_ERR_NULL	invalid client handle
GOLIOTH_ERR_INVALID_STATE	client is not running, currently stopped
GOLIOTH_ERR_QUEUE_FULL	request queue is full, this request is dropped
GOLIOTH_ERR_TIMEOUT	response not received from server, timeout occurred

golioth_lightdb_get_string_sync()

enum golioth_status golioth_lightdb_get_string_sync	(	struct golioth_client *	client,
		const char *	path,
		char *	strbuf,
		size_t	strbuf_size,
		int32_t	timeout_s )

Similar to golioth_lightdb_get_int_sync, but for type string.

golioth_lightdb_get_sync()

enum golioth_status golioth_lightdb_get_sync	(	struct golioth_client *	client,
		const char *	path,
		enum golioth_content_type	content_type,
		uint8_t *	buf,
		size_t *	buf_size,
		int32_t	timeout_s )

Similar to golioth_lightdb_get_int_sync, but for objects.

golioth_lightdb_observe_async()

enum golioth_status golioth_lightdb_observe_async	(	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 asynchronously

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_async()

enum golioth_status golioth_lightdb_set_async	(	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 asynchronously

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

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_async()

enum golioth_status golioth_lightdb_set_bool_async	(	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 asynchronously

Same as golioth_lightdb_set_int_async, but for type bool

golioth_lightdb_set_bool_sync()

enum golioth_status golioth_lightdb_set_bool_sync	(	struct golioth_client *	client,
		const char *	path,
		bool	value,
		int32_t	timeout_s )

Set a bool in LightDB state at a particular path synchronously

Same as golioth_lightdb_set_int_sync, but for type bool

golioth_lightdb_set_float_async()

enum golioth_status golioth_lightdb_set_float_async	(	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 asynchronously

Same as golioth_lightdb_set_int_async, but for type float

golioth_lightdb_set_float_sync()

enum golioth_status golioth_lightdb_set_float_sync	(	struct golioth_client *	client,
		const char *	path,
		float	value,
		int32_t	timeout_s )

golioth_lightdb_set_int_async()

enum golioth_status golioth_lightdb_set_int_async	(	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 asynchronously

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_int_sync()

enum golioth_status golioth_lightdb_set_int_sync	(	struct golioth_client *	client,
		const char *	path,
		int32_t	value,
		int32_t	timeout_s )

Set an integer in LightDB state at a particular path synchronously

This function will block until one of three things happen (whichever comes first):

1. A response is received from the server
2. The user-provided timeout_s period expires without receiving a response
3. The default GOLIOTH_COAP_RESPONSE_TIMEOUT_S period expires without receiving a response

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
timeout_s	The timeout, in seconds, for receiving a server response

Return values

GOLIOTH_OK	response received from server, set was successful
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_ERR_TIMEOUT	response not received from server, timeout occurred

golioth_lightdb_set_string_async()

enum golioth_status golioth_lightdb_set_string_async	(	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 asynchronously

Same as golioth_lightdb_set_int_async, but for type string

golioth_lightdb_set_string_sync()

enum golioth_status golioth_lightdb_set_string_sync	(	struct golioth_client *	client,
		const char *	path,
		const char *	str,
		size_t	str_len,
		int32_t	timeout_s )

golioth_lightdb_set_sync()

enum golioth_status golioth_lightdb_set_sync	(	struct golioth_client *	client,
		const char *	path,
		enum golioth_content_type	content_type,
		const uint8_t *	buf,
		size_t	buf_len,
		int32_t	timeout_s )

Set am object in LightDB state at a particular path synchronously

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

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
timeout_s	The timeout, in seconds, for receiving a server response