golioth_settings

Typedefs
typedef enum golioth_settings_status(*	golioth_int_setting_cb) (int32_t new_value, void *arg)
typedef enum golioth_settings_status(*	golioth_bool_setting_cb) (bool new_value, void *arg)
typedef enum golioth_settings_status(*	golioth_float_setting_cb) (float new_value, void *arg)
typedef enum golioth_settings_status(*	golioth_string_setting_cb) (const char *new_value, size_t new_value_len, void *arg)

Enumerations
enum	golioth_settings_status {   GOLIOTH_SETTINGS_SUCCESS = 0 , GOLIOTH_SETTINGS_KEY_NOT_RECOGNIZED = 1 , GOLIOTH_SETTINGS_KEY_NOT_VALID = 2 , GOLIOTH_SETTINGS_VALUE_FORMAT_NOT_VALID = 3 ,   GOLIOTH_SETTINGS_VALUE_OUTSIDE_RANGE = 4 , GOLIOTH_SETTINGS_VALUE_STRING_TOO_LONG = 5 , GOLIOTH_SETTINGS_GENERAL_ERROR = 6 }
	Enumeration of Settings status codes. More...
enum	golioth_settings_value_type {   GOLIOTH_SETTINGS_VALUE_TYPE_UNKNOWN , GOLIOTH_SETTINGS_VALUE_TYPE_INT , GOLIOTH_SETTINGS_VALUE_TYPE_BOOL , GOLIOTH_SETTINGS_VALUE_TYPE_FLOAT ,   GOLIOTH_SETTINGS_VALUE_TYPE_STRING }
	Different types of setting values. More...

Functions
struct golioth_settings *	golioth_settings_init (struct golioth_client *client)
enum golioth_status	golioth_settings_deinit (struct golioth_settings *settings)
enum golioth_status	golioth_settings_register_int (struct golioth_settings *settings, const char *setting_name, golioth_int_setting_cb callback, void *callback_arg)
enum golioth_status	golioth_settings_register_int_with_range (struct golioth_settings *settings, const char *setting_name, int32_t min_val, int32_t max_val, golioth_int_setting_cb callback, void *callback_arg)
enum golioth_status	golioth_settings_register_bool (struct golioth_settings *settings, const char *setting_name, golioth_bool_setting_cb callback, void *callback_arg)
	Same as golioth_settings_register_int, but for type bool.
enum golioth_status	golioth_settings_register_float (struct golioth_settings *settings, const char *setting_name, golioth_float_setting_cb callback, void *callback_arg)
	Same as golioth_settings_register_int, but for type float.
enum golioth_status	golioth_settings_register_string (struct golioth_settings *settings, const char *setting_name, golioth_string_setting_cb callback, void *callback_arg)
	Same as golioth_settings_register_int, but for type string.

Detailed Description

Functions for interacting with the Golioth Settings service

The Settings service is for long-lived persistent configuration data. Settings are configured/written from the cloud and read by the device. The device observes for settings updates, and reports status of applying the settings to the cloud.

Each setting is a key/value pair, where the key is a string and the value can be int32_t, bool, float, or string.

Overall, the flow is:

1. Application registers a callback to handle each setting.
2. This library observes for settings changes from cloud.
3. Cloud pushes settings changes to device.
4. For each setting, this library calls user-registered callbacks.
5. This library reports status of applying settings to cloud.

For each setting recieved, this library will check:

• The key is known/registered
• The type matches the registered type
• (integer only) The value is within the min/max range

Typedef Documentation

golioth_bool_setting_cb

typedef enum golioth_settings_status(* golioth_bool_setting_cb) (bool new_value, void *arg)

Definition at line 1 of file settings.h.

golioth_float_setting_cb

typedef enum golioth_settings_status(* golioth_float_setting_cb) (float new_value, void *arg)

Definition at line 1 of file settings.h.

golioth_int_setting_cb

typedef enum golioth_settings_status(* golioth_int_setting_cb) (int32_t new_value, void *arg)

Callback function types for golioth_settings_register_*

Parameters

new_value	The setting value received from Golioth cloud
arg	User's registered callback arg

Returns

GOLIOTH_SETTINGS_OK - the setting was applied successfully

Otherwise - there was an error applying the setting

Definition at line 1 of file settings.h.

golioth_string_setting_cb

typedef enum golioth_settings_status(* golioth_string_setting_cb) (const char *new_value, size_t new_value_len, void *arg)

Definition at line 1 of file settings.h.

Enumeration Type Documentation

golioth_settings_status

enum golioth_settings_status

Enumeration of Settings status codes.

Enumerator
GOLIOTH_SETTINGS_SUCCESS	Setting applied successfully to the device, stored in NVS.
GOLIOTH_SETTINGS_KEY_NOT_RECOGNIZED	The setting key is not recognized, this setting is unknown.
GOLIOTH_SETTINGS_KEY_NOT_VALID	The setting key is too long, ill-formatted.
GOLIOTH_SETTINGS_VALUE_FORMAT_NOT_VALID	The setting value is improperly formatted.
GOLIOTH_SETTINGS_VALUE_OUTSIDE_RANGE	The setting value is outside of allowed range.
GOLIOTH_SETTINGS_VALUE_STRING_TOO_LONG	The setting value string is too long, exceeds max length.
GOLIOTH_SETTINGS_GENERAL_ERROR	Other general error (e.g. I/O error)

Definition at line 51 of file settings.h.

golioth_settings_value_type

enum golioth_settings_value_type

Different types of setting values.

Enumerator
GOLIOTH_SETTINGS_VALUE_TYPE_UNKNOWN
GOLIOTH_SETTINGS_VALUE_TYPE_INT
GOLIOTH_SETTINGS_VALUE_TYPE_BOOL
GOLIOTH_SETTINGS_VALUE_TYPE_FLOAT
GOLIOTH_SETTINGS_VALUE_TYPE_STRING

Definition at line 70 of file settings.h.

Function Documentation

golioth_settings_deinit()

enum golioth_status golioth_settings_deinit

(

struct golioth_settings *

settings

)

Deinitialize the Settings service

Cancel all registered settings and free the Golioth Settings service handle.

Parameters

settings

Golioth Settings service handle.

Returns

GOLIOTH_OK - RPC service successfully deinitialized

otherwise - Error deinitializing the Settings service

golioth_settings_init()

struct golioth_settings * golioth_settings_init

(

struct golioth_client *

client

)

Initialize the Settings service

Parameters

client

Client handle

Returns

pointer to golioth settings struct

NULL - Error initializing Settings service

golioth_settings_register_bool()

enum golioth_status golioth_settings_register_bool	(	struct golioth_settings *	settings,
		const char *	setting_name,
		golioth_bool_setting_cb	callback,
		void *	callback_arg )

Same as golioth_settings_register_int, but for type bool.

golioth_settings_register_float()

enum golioth_status golioth_settings_register_float	(	struct golioth_settings *	settings,
		const char *	setting_name,
		golioth_float_setting_cb	callback,
		void *	callback_arg )

Same as golioth_settings_register_int, but for type float.

golioth_settings_register_int()

enum golioth_status golioth_settings_register_int	(	struct golioth_settings *	settings,
		const char *	setting_name,
		golioth_int_setting_cb	callback,
		void *	callback_arg )

Register a specific setting of type int

Parameters

settings	Settings handle
setting_name	The name of the setting. This is expected to be a literal string, therefore on the pointer is registered (not a full copy of the string).
callback	Callback function that will be called when the setting value is received from Golioth cloud
callback_arg	General-purpose user argument, forwarded as-is to callback, can be NULL.

Return values

GOLIOTH_OK	Setting registered successfully
GOLIOTH_ERR_MEM_ALLOC	Max number of registered settings exceeded
GOLIOTH_ERR_NOT_IMPLEMENTED	If Golioth settings are disabled in config
GOLIOTH_ERR_NULL	callback is NULL

golioth_settings_register_int_with_range()

enum golioth_status golioth_settings_register_int_with_range	(	struct golioth_settings *	settings,
		const char *	setting_name,
		int32_t	min_val,
		int32_t	max_val,
		golioth_int_setting_cb	callback,
		void *	callback_arg )

Same as golioth_settings_register_int, but with specific min and max value which will be checked by this library.

golioth_settings_register_string()

enum golioth_status golioth_settings_register_string	(	struct golioth_settings *	settings,
		const char *	setting_name,
		golioth_string_setting_cb	callback,
		void *	callback_arg )

Same as golioth_settings_register_int, but for type string.