Modules
	Settings backend interface

	Settings name processing
	API for const name processing.

	Settings subsystem runtime
	API for runtime settings.

Data Structures
struct	settings_handler

struct	settings_handler_static

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)

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

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

Functions
int	settings_subsys_init (void)

int	settings_register (struct settings_handler *cf)

int	settings_load (void)

int	settings_load_subtree (const char *subtree)

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

int	settings_save (void)

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

int	settings_delete (const char *name)

int	settings_commit (void)

int	settings_commit_subtree (const char *subtree)

Detailed Description

Macro Definition Documentation

◆ SETTINGS_EXTRA_LEN

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

#include <include/settings/settings.h>

◆ SETTINGS_MAX_DIR_DEPTH

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

#include <include/settings/settings.h>

◆ SETTINGS_MAX_NAME_LEN

#define SETTINGS_MAX_NAME_LEN (8 * SETTINGS_MAX_DIR_DEPTH)

#include <include/settings/settings.h>

◆ SETTINGS_MAX_VAL_LEN

#define SETTINGS_MAX_VAL_LEN 256

#include <include/settings/settings.h>

◆ SETTINGS_NAME_END

#define SETTINGS_NAME_END '='

#include <include/settings/settings.h>

◆ SETTINGS_NAME_SEPARATOR

#define SETTINGS_NAME_SEPARATOR '/'

#include <include/settings/settings.h>

◆ SETTINGS_STATIC_HANDLER_DEFINE

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

#include <include/settings/settings.h>

Value:

        const STRUCT_SECTION_ITERABLE(settings_handler_static,               \
                                      settings_handler_ ## _hname) = {       \
                .name = _tree,                                               \
                .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)

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 <include/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.

key[in] the name with skipped part that was used as name in handler registration
len[in] the size of the data found in the backend.
read_cb[in] function provided to read the data from the backend.
cb_arg[in] arguments for the read function provided by the backend.

Returns: When nonzero value is returned, further subtree searching is stopped. Use with care as some settings backends would iterate through old values, and the current value is returned last.

◆ settings_read_cb

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

#include <include/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 <include/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 <include/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 <include/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 <include/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 <include/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 <include/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 <include/settings/settings.h>

Register a handler for settings items stored in RAM.

Parameters

cf	Structure containing registration info.

Returns: 0 on success, non-zero on failure.

◆ settings_save()

int settings_save ( void )

#include <include/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 <include/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_subsys_init()

int settings_subsys_init ( void )

#include <include/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.

	Zephyr API Documentation 3.0.0 A Scalable Open Source RTOS
3.0.0

Modules

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SETTINGS_EXTRA_LEN

◆ SETTINGS_MAX_DIR_DEPTH

◆ SETTINGS_MAX_NAME_LEN

◆ SETTINGS_MAX_VAL_LEN

◆ SETTINGS_NAME_END

◆ SETTINGS_NAME_SEPARATOR

◆ SETTINGS_STATIC_HANDLER_DEFINE

Typedef Documentation

◆ settings_load_direct_cb

◆ settings_read_cb

Function Documentation

◆ settings_commit()

◆ settings_commit_subtree()

◆ settings_delete()

◆ settings_load()

◆ settings_load_subtree()

◆ settings_load_subtree_direct()

◆ settings_register()

◆ settings_save()

◆ settings_save_one()

◆ settings_subsys_init()