Settings

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_WITH_CPRIO(_hname, _tree, _get, _set, _commit, _export, _cprio)
	Define a static handler for settings items.
#define	SETTINGS_STATIC_HANDLER_DEFINE(_hname, _tree, _get, _set, _commit, _export)

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_with_cprio (struct settings_handler *cf, int cprio)
	Register a handler for settings items stored in RAM with commit priority.
int	settings_register (struct settings_handler *cf)
	Register a handler for settings items stored in RAM with commit priority set to default.
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)

#include <zephyr/settings/settings.h>

SETTINGS_MAX_DIR_DEPTH

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

#include <zephyr/settings/settings.h>

SETTINGS_MAX_NAME_LEN

#define SETTINGS_MAX_NAME_LEN   (8 * SETTINGS_MAX_DIR_DEPTH)

#include <zephyr/settings/settings.h>

SETTINGS_MAX_VAL_LEN

#define SETTINGS_MAX_VAL_LEN   256

#include <zephyr/settings/settings.h>

SETTINGS_NAME_END

#define SETTINGS_NAME_END   '='

#include <zephyr/settings/settings.h>

SETTINGS_NAME_SEPARATOR

#define SETTINGS_NAME_SEPARATOR   '/'

#include <zephyr/settings/settings.h>

SETTINGS_STATIC_HANDLER_DEFINE

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

#include <zephyr/settings/settings.h>

Value:

        SETTINGS_STATIC_HANDLER_DEFINE_WITH_CPRIO(_hname, _tree, _get, _set, \
                _commit, _export, 0)

SETTINGS_STATIC_HANDLER_DEFINE_WITH_CPRIO

#define SETTINGS_STATIC_HANDLER_DEFINE_WITH_CPRIO	(		_hname,
			_tree,
			_get,
			_set,
			_commit,
			_export,
			_cprio )

#include <zephyr/settings/settings.h>

Value:

        const STRUCT_SECTION_ITERABLE(settings_handler_static,               \
                                      settings_handler_ ## _hname) = {       \
                .name = _tree,                                               \
                .cprio = _cprio,                                             \
                .h_get = _get,                                               \
                .h_set = _set,                                               \
                .h_commit = _commit,                                         \
                .h_export = _export,                                         \
        }

Define a static handler for settings items.

Parameters

_hname	handler name
_tree	subtree name
_get	get routine (can be NULL)
_set	set routine (can be NULL)
_commit	commit routine (can be NULL)
_export	export routine (can be NULL)
_cprio	commit priority (lower value is higher priority)

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]	key	the name with skipped part that was used as name in handler registration
[in]	len	the size of the data found in the backend.
[in]	read_cb	function provided to read the data from the backend.
[in,out]	cb_arg	arguments for the read function provided by the backend.
[in,out]	param	parameter 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_arg	arguments for the read function. Appropriate cb_arg is transferred to h_set handler implementation by the backend.
[out]	data	the destination buffer
[in]	len	length 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]

subtree

name 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

name	Name/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]

subtree

name 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]	subtree	subtree name of the subtree to be loaded.
[in]	cb	pointer to the callback function.
[in,out]	param	parameter 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 with commit priority set to default.

Parameters

cf	Structure containing registration info.

Returns

0 on success, non-zero on failure.

settings_register_with_cprio()

int settings_register_with_cprio	(	struct settings_handler *	cf,
		int	cprio )

#include <zephyr/settings/settings.h>

Register a handler for settings items stored in RAM with commit priority.

Parameters

cf	Structure containing registration info.
cprio	Commit priority (lower value is higher priority).

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

name	Name/key of the settings item.
value	Pointer to the value of the settings item. This value will be transferred to the settings_handler::h_export handler implementation.
val_len	Length 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]

subtree

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