Golioth Firmware SDK
Loading...
Searching...
No Matches
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:

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_valueThe setting value received from Golioth cloud
argUser'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

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

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
settingsGolioth 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
clientClient 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
settingsSettings handle
setting_nameThe 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).
callbackCallback function that will be called when the setting value is received from Golioth cloud
callback_argGeneral-purpose user argument, forwarded as-is to callback, can be NULL.
Return values
GOLIOTH_OKSetting registered successfully
GOLIOTH_ERR_MEM_ALLOCMax number of registered settings exceeded
GOLIOTH_ERR_NOT_IMPLEMENTEDIf Golioth settings are disabled in config
GOLIOTH_ERR_NULLcallback 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.