Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

Topics

 Settings backend interface
 settings
 
 Settings name processing
 
 
 Settings subsystem runtime
 
 

Data Structures

struct  settings_handler
 Config handlers for subtree implement a set of handler functions. More...
 
struct  settings_handler_static
 Config handlers without the node element, used for static handlers. More...
 

Macros

#define SETTINGS_MAX_DIR_DEPTH   8 /* max depth of settings tree */
 
#define SETTINGS_MAX_NAME_LEN   (8 * SETTINGS_MAX_DIR_DEPTH)
 
#define SETTINGS_MAX_VAL_LEN   256
 
#define SETTINGS_NAME_SEPARATOR   '/'
 
#define SETTINGS_NAME_END   '='
 
#define SETTINGS_EXTRA_LEN   ((SETTINGS_MAX_DIR_DEPTH - 1) + 2)
 
#define SETTINGS_STATIC_HANDLER_DEFINE(_hname, _tree, _get, _set, _commit, _export)
 Define a static handler for settings items.
 

Typedefs

typedef ssize_t(* settings_read_cb) (void *cb_arg, void *data, size_t len)
 Function used to read the data from the settings storage in h_set handler implementations.
 
typedef int(* settings_load_direct_cb) (const char *key, size_t len, settings_read_cb read_cb, void *cb_arg, void *param)
 Callback function used for direct loading.
 

Functions

int settings_subsys_init (void)
 Initialization of settings and backend.
 
int settings_register (struct settings_handler *cf)
 Register a handler for settings items stored in RAM.
 
int settings_load (void)
 Load serialized items from registered persistence sources.
 
int settings_load_subtree (const char *subtree)
 Load limited set of serialized items from registered persistence sources.
 
int settings_load_subtree_direct (const char *subtree, settings_load_direct_cb cb, void *param)
 Load limited set of serialized items using given callback.
 
int settings_save (void)
 Save currently running serialized items.
 
int settings_save_subtree (const char *subtree)
 Save limited set of currently running serialized items.
 
int settings_save_one (const char *name, const void *value, size_t val_len)
 Write a single serialized value to persisted storage (if it has changed value).
 
int settings_delete (const char *name)
 Delete a single serialized in persisted storage.
 
int settings_commit (void)
 Call commit for all settings handler.
 
int settings_commit_subtree (const char *subtree)
 Call commit for settings handler that belong to subtree.
 

Detailed Description

Since
1.12
Version
1.0.0

Macro Definition Documentation

◆ SETTINGS_EXTRA_LEN

#define SETTINGS_EXTRA_LEN   ((SETTINGS_MAX_DIR_DEPTH - 1) + 2)

◆ SETTINGS_MAX_DIR_DEPTH

#define SETTINGS_MAX_DIR_DEPTH   8 /* max depth of settings tree */

◆ SETTINGS_MAX_NAME_LEN

#define SETTINGS_MAX_NAME_LEN   (8 * SETTINGS_MAX_DIR_DEPTH)

◆ SETTINGS_MAX_VAL_LEN

#define SETTINGS_MAX_VAL_LEN   256

◆ SETTINGS_NAME_END

#define SETTINGS_NAME_END   '='

◆ SETTINGS_NAME_SEPARATOR

#define SETTINGS_NAME_SEPARATOR   '/'

◆ SETTINGS_STATIC_HANDLER_DEFINE

#define SETTINGS_STATIC_HANDLER_DEFINE ( _hname,
_tree,
_get,
_set,
_commit,
_export )

#include <zephyr/settings/settings.h>

Value:
settings_handler_ ## _hname) = { \
.name = _tree, \
.h_get = _get, \
.h_set = _set, \
.h_commit = _commit, \
.h_export = _export, \
}
#define STRUCT_SECTION_ITERABLE(struct_type, varname)
Defines a new element for an iterable section.
Definition iterable_sections.h:216
Config handlers without the node element, used for static handlers.
Definition settings.h:134

Define a static handler for settings items.

Parameters
_hnamehandler name
_treesubtree name
_getget routine (can be NULL)
_setset routine (can be NULL)
_commitcommit routine (can be NULL)
_exportexport routine (can be NULL)

This creates a variable hname prepended by settings_handler.

Typedef Documentation

◆ settings_load_direct_cb

typedef int(* settings_load_direct_cb) (const char *key, size_t len, settings_read_cb read_cb, void *cb_arg, void *param)

#include <zephyr/settings/settings.h>

Callback function used for direct loading.

Used by settings_load_subtree_direct function.

Parameters
[in]keythe name with skipped part that was used as name in handler registration
[in]lenthe size of the data found in the backend.
[in]read_cbfunction provided to read the data from the backend.
[in,out]cb_argarguments for the read function provided by the backend.
[in,out]paramparameter given to the settings_load_subtree_direct function.
Returns
When nonzero value is returned, further subtree searching is stopped.

◆ settings_read_cb

typedef ssize_t(* settings_read_cb) (void *cb_arg, void *data, size_t len)

#include <zephyr/settings/settings.h>

Function used to read the data from the settings storage in h_set handler implementations.

Parameters
[in]cb_argarguments for the read function. Appropriate cb_arg is transferred to h_set handler implementation by the backend.
[out]datathe destination buffer
[in]lenlength of read
Returns
positive: Number of bytes read, 0: key-value pair is deleted. On error returns -ERRNO code.

Function Documentation

◆ settings_commit()

int settings_commit ( void )

#include <zephyr/settings/settings.h>

Call commit for all settings handler.

This should apply all settings which has been set, but not applied yet.

Returns
0 on success, non-zero on failure.

◆ settings_commit_subtree()

int settings_commit_subtree ( const char * subtree)

#include <zephyr/settings/settings.h>

Call commit for settings handler that belong to subtree.

This should apply all settings which has been set, but not applied yet.

Parameters
[in]subtreename of the subtree to be committed.
Returns
0 on success, non-zero on failure.

◆ settings_delete()

int settings_delete ( const char * name)

#include <zephyr/settings/settings.h>

Delete a single serialized in persisted storage.

Deleting an existing key-value pair in the settings mean to set its value to NULL.

Parameters
nameName/key of the settings item.
Returns
0 on success, non-zero on failure.

◆ settings_load()

int settings_load ( void )

#include <zephyr/settings/settings.h>

Load serialized items from registered persistence sources.

Handlers for serialized item subtrees registered earlier will be called for encountered values.

Returns
0 on success, non-zero on failure.

◆ settings_load_subtree()

int settings_load_subtree ( const char * subtree)

#include <zephyr/settings/settings.h>

Load limited set of serialized items from registered persistence sources.

Handlers for serialized item subtrees registered earlier will be called for encountered values that belong to the subtree.

Parameters
[in]subtreename of the subtree to be loaded.
Returns
0 on success, non-zero on failure.

◆ settings_load_subtree_direct()

int settings_load_subtree_direct ( const char * subtree,
settings_load_direct_cb cb,
void * param )

#include <zephyr/settings/settings.h>

Load limited set of serialized items using given callback.

This function bypasses the normal data workflow in settings module. All the settings values that are found are passed to the given callback.

Note
This function does not call commit function. It works as a blocking function, so it is up to the user to call any kind of commit function when this operation ends.
Parameters
[in]subtreesubtree name of the subtree to be loaded.
[in]cbpointer to the callback function.
[in,out]paramparameter to be passed when callback function is called.
Returns
0 on success, non-zero on failure.

◆ settings_register()

int settings_register ( struct settings_handler * cf)

#include <zephyr/settings/settings.h>

Register a handler for settings items stored in RAM.

Parameters
cfStructure containing registration info.
Returns
0 on success, non-zero on failure.

◆ settings_save()

int settings_save ( void )

#include <zephyr/settings/settings.h>

Save currently running serialized items.

All serialized items which are different from currently persisted values will be saved.

Returns
0 on success, non-zero on failure.

◆ settings_save_one()

int settings_save_one ( const char * name,
const void * value,
size_t val_len )

#include <zephyr/settings/settings.h>

Write a single serialized value to persisted storage (if it has changed value).

Parameters
nameName/key of the settings item.
valuePointer to the value of the settings item. This value will be transferred to the settings_handler::h_export handler implementation.
val_lenLength of the value.
Returns
0 on success, non-zero on failure.

◆ settings_save_subtree()

int settings_save_subtree ( const char * subtree)

#include <zephyr/settings/settings.h>

Save limited set of currently running serialized items.

All serialized items that belong to subtree and which are different from currently persisted values will be saved.

Parameters
[in]subtreename of the subtree to be loaded.
Returns
0 on success, non-zero on failure.

◆ settings_subsys_init()

int settings_subsys_init ( void )

#include <zephyr/settings/settings.h>

Initialization of settings and backend.

Can be called at application startup. In case the backend is a FS Remember to call it after the FS was mounted. For FCB backend it can be called without such a restriction.

Returns
0 on success, non-zero on failure.