Zephyr API Documentation 4.0.0-rc2
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
settings.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2018 Nordic Semiconductor ASA
3 * Copyright (c) 2015 Runtime Inc
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 */
7
8#ifndef ZEPHYR_INCLUDE_SETTINGS_SETTINGS_H_
9#define ZEPHYR_INCLUDE_SETTINGS_SETTINGS_H_
10
11#include <sys/types.h>
12#include <zephyr/sys/util.h>
13#include <zephyr/sys/slist.h>
15#include <stdint.h>
16
17#ifdef __cplusplus
18extern "C" {
19#endif
20
21
37#define SETTINGS_MAX_DIR_DEPTH 8 /* max depth of settings tree */
38#define SETTINGS_MAX_NAME_LEN (8 * SETTINGS_MAX_DIR_DEPTH)
39#define SETTINGS_MAX_VAL_LEN 256
40#define SETTINGS_NAME_SEPARATOR '/'
41#define SETTINGS_NAME_END '='
42
43/* place for settings additions:
44 * up to 7 separators, '=', '\0'
45 */
46#define SETTINGS_EXTRA_LEN ((SETTINGS_MAX_DIR_DEPTH - 1) + 2)
47
61typedef ssize_t (*settings_read_cb)(void *cb_arg, void *data, size_t len);
62
69
70 const char *name;
73 int cprio;
76 int (*h_get)(const char *key, char *val, int val_len_max);
88 int (*h_set)(const char *key, size_t len, settings_read_cb read_cb,
89 void *cb_arg);
103 int (*h_commit)(void);
110 int (*h_export)(int (*export_func)(const char *name, const void *val,
111 size_t val_len));
130};
131
138
139 const char *name;
142 int cprio;
145 int (*h_get)(const char *key, char *val, int val_len_max);
157 int (*h_set)(const char *key, size_t len, settings_read_cb read_cb,
158 void *cb_arg);
172 int (*h_commit)(void);
177 int (*h_export)(int (*export_func)(const char *name, const void *val,
178 size_t val_len));
194};
195
211#define SETTINGS_STATIC_HANDLER_DEFINE_WITH_CPRIO(_hname, _tree, _get, _set, \
212 _commit, _export, _cprio) \
213 const STRUCT_SECTION_ITERABLE(settings_handler_static, \
214 settings_handler_ ## _hname) = { \
215 .name = _tree, \
216 .cprio = _cprio, \
217 .h_get = _get, \
218 .h_set = _set, \
219 .h_commit = _commit, \
220 .h_export = _export, \
221 }
222
223/* Handlers without commit priority are set to priority O */
224#define SETTINGS_STATIC_HANDLER_DEFINE(_hname, _tree, _get, _set, _commit, \
225 _export) \
226 SETTINGS_STATIC_HANDLER_DEFINE_WITH_CPRIO(_hname, _tree, _get, _set, \
227 _commit, _export, 0)
228
239
250 int cprio);
251
261
270
279int settings_load_subtree(const char *subtree);
280
297 const char *key,
298 size_t len,
299 settings_read_cb read_cb,
300 void *cb_arg,
301 void *param);
302
321 const char *subtree,
323 void *param);
324
332
341int settings_save_subtree(const char *subtree);
342
354int settings_save_one(const char *name, const void *value, size_t val_len);
355
366int settings_delete(const char *name);
367
375
384int settings_commit_subtree(const char *subtree);
385
397/*
398 * API for config storage
399 */
400
401struct settings_store_itf;
402
413
438
445 int (*csi_load)(struct settings_store *cs,
446 const struct settings_load_arg *arg);
460 int (*csi_save_start)(struct settings_store *cs);
467 int (*csi_save)(struct settings_store *cs, const char *name,
468 const char *value, size_t val_len);
478 int (*csi_save_end)(struct settings_store *cs);
490 void *(*csi_storage_get)(struct settings_store *cs);
491};
492
500
508
509
510/*
511 * API for handler lookup
512 */
513
523 const char **next);
524
539 size_t len,
540 settings_read_cb read_cb,
541 void *read_cb_arg,
542 const struct settings_load_arg *load_arg);
574int settings_name_steq(const char *name, const char *key, const char **next);
575
586int settings_name_next(const char *name, const char **next);
591#ifdef CONFIG_SETTINGS_RUNTIME
592
609int settings_runtime_set(const char *name, const void *data, size_t len);
610
620int settings_runtime_get(const char *name, void *data, size_t len);
621
634#endif /* CONFIG_SETTINGS_RUNTIME */
635
647int settings_storage_get(void **storage);
648
649#ifdef __cplusplus
650}
651#endif
652
653#endif /* ZEPHYR_INCLUDE_SETTINGS_SETTINGS_H_ */
void settings_dst_register(struct settings_store *cs)
Register a backend handler acting as destination.
struct settings_handler_static * settings_parse_and_lookup(const char *name, const char **next)
Parses a key to an array of elements and locate corresponding module handler.
void settings_src_register(struct settings_store *cs)
Register a backend handler acting as source.
int settings_call_set_handler(const char *name, size_t len, settings_read_cb read_cb, void *read_cb_arg, const struct settings_load_arg *load_arg)
Calls settings handler.
int settings_name_steq(const char *name, const char *key, const char **next)
Compares the start of name with a key.
int settings_name_next(const char *name, const char **next)
determine the number of characters before the first separator
int settings_runtime_get(const char *name, void *data, size_t len)
Get a value corresponding to a key from a module handler.
int settings_runtime_set(const char *name, const void *data, size_t len)
Set a value with a specific key to a module handler.
int settings_runtime_commit(const char *name)
Apply settings in a module handler.
int settings_delete(const char *name)
Delete a single serialized in persisted storage.
int settings_commit_subtree(const char *subtree)
Call commit for settings handler that belong to subtree.
int settings_load_subtree_direct(const char *subtree, settings_load_direct_cb cb, void *param)
Load limited set of serialized items using given callback.
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.
Definition settings.h:61
int settings_commit(void)
Call commit for all settings handler.
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.
Definition settings.h:296
int settings_save(void)
Save currently running serialized items.
int settings_load(void)
Load serialized items from registered persistence sources.
int settings_save_subtree(const char *subtree)
Save limited set of currently running serialized items.
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_subtree(const char *subtree)
Load limited set of serialized items from registered persistence sources.
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_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_subsys_init(void)
Initialization of settings and backend.
struct _snode sys_snode_t
Single-linked list node structure.
Definition slist.h:39
__SIZE_TYPE__ ssize_t
Definition types.h:28
int settings_storage_get(void **storage)
Get the storage instance used by zephyr.
Config handlers without the node element, used for static handlers.
Definition settings.h:137
int(* h_commit)(void)
This handler gets called after settings has been loaded in full.
Definition settings.h:172
int(* h_set)(const char *key, size_t len, settings_read_cb read_cb, void *cb_arg)
Set value handler of settings items identified by keyword names.
Definition settings.h:157
int cprio
Priority of commit, lower value is higher priority.
Definition settings.h:142
const char * name
Name of subtree.
Definition settings.h:139
int(* h_export)(int(*export_func)(const char *name, const void *val, size_t val_len))
This gets called to dump all current settings items.
Definition settings.h:177
int(* h_get)(const char *key, char *val, int val_len_max)
Get values handler of settings items identified by keyword names.
Definition settings.h:145
Config handlers for subtree implement a set of handler functions.
Definition settings.h:68
int(* h_export)(int(*export_func)(const char *name, const void *val, size_t val_len))
This gets called to dump all current settings items.
Definition settings.h:110
sys_snode_t node
Linked list node info for module internal usage.
Definition settings.h:128
int(* h_set)(const char *key, size_t len, settings_read_cb read_cb, void *cb_arg)
Set value handler of settings items identified by keyword names.
Definition settings.h:88
int(* h_get)(const char *key, char *val, int val_len_max)
Get values handler of settings items identified by keyword names.
Definition settings.h:76
const char * name
Name of subtree.
Definition settings.h:70
int cprio
Priority of commit, lower value is higher priority.
Definition settings.h:73
int(* h_commit)(void)
This handler gets called after settings has been loaded in full.
Definition settings.h:103
Arguments for data loading.
Definition settings.h:418
const char * subtree
Name of the subtree to be loaded.
Definition settings.h:424
void * param
Parameter for callback function.
Definition settings.h:436
settings_load_direct_cb cb
Pointer to the callback function.
Definition settings.h:430
Backend handler functions.
Definition settings.h:444
int(* csi_load)(struct settings_store *cs, const struct settings_load_arg *arg)
Loads values from storage limited to subtree defined by subtree.
Definition settings.h:445
int(* csi_save_end)(struct settings_store *cs)
Handler called after an export operation.
Definition settings.h:478
int(* csi_save_start)(struct settings_store *cs)
Handler called before an export operation.
Definition settings.h:460
int(* csi_save)(struct settings_store *cs, const char *name, const char *value, size_t val_len)
Save a single key-value pair to storage.
Definition settings.h:467
Backend handler node for storage handling.
Definition settings.h:406
sys_snode_t cs_next
Linked list node info for internal usage.
Definition settings.h:407
const struct settings_store_itf * cs_itf
Backend handler structure.
Definition settings.h:410
Misc utilities.