settings.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018 Nordic Semiconductor ASA
 * Copyright (c) 2015 Runtime Inc
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_SETTINGS_SETTINGS_H_
#define ZEPHYR_INCLUDE_SETTINGS_SETTINGS_H_
 
#include <sys/types.h>
#include <zephyr/sys/util.h>
#include <zephyr/sys/slist.h>
#include <zephyr/sys/iterable_sections.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
 
#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 '='
 
/* place for settings additions:
 * up to 7 separators, '=', '\0'
 */
#define SETTINGS_EXTRA_LEN ((SETTINGS_MAX_DIR_DEPTH - 1) + 2)
 
/* Maximum Settings name length including separators */
#define SETTINGS_FULL_NAME_LEN ((SETTINGS_MAX_NAME_LEN) + (SETTINGS_EXTRA_LEN) + 1)
 
typedef ssize_t (*settings_read_cb)(void *cb_arg, void *data, size_t len);
 
struct settings_handler {
 
        const char *name;
        int cprio;
        int (*h_get)(const char *key, char *val, int val_len_max);
        int (*h_set)(const char *key, size_t len, settings_read_cb read_cb,
                     void *cb_arg);
        int (*h_commit)(void);
        int (*h_export)(int (*export_func)(const char *name, const void *val,
                                           size_t val_len));
        sys_snode_t node;
};
struct settings_handler {…};
 
struct settings_handler_static {
 
        const char *name;
        int cprio;
        int (*h_get)(const char *key, char *val, int val_len_max);
        int (*h_set)(const char *key, size_t len, settings_read_cb read_cb,
                     void *cb_arg);
        int (*h_commit)(void);
        int (*h_export)(int (*export_func)(const char *name, const void *val,
                                           size_t val_len));
};
struct settings_handler_static {…};
 
#define SETTINGS_STATIC_HANDLER_DEFINE_WITH_CPRIO(_hname, _tree, _get, _set, \
                                                  _commit, _export, _cprio)  \
        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,                                         \
        }
 
/* Handlers without commit priority are set to priority O */
#define SETTINGS_STATIC_HANDLER_DEFINE(_hname, _tree, _get, _set, _commit,   \
                                       _export)                              \
        SETTINGS_STATIC_HANDLER_DEFINE_WITH_CPRIO(_hname, _tree, _get, _set, \
                _commit, _export, 0)
 
int settings_subsys_init(void);
 
int settings_register_with_cprio(struct settings_handler *cf,
                                 int cprio);
 
int settings_register(struct settings_handler *cf);
 
int settings_load(void);
 
int settings_load_subtree(const char *subtree);
 
ssize_t settings_load_one(const char *name, void *buf, size_t buf_len);
 
ssize_t settings_get_val_len(const char *key);
 
typedef int (*settings_load_direct_cb)(
        const char      *key,
        size_t           len,
        settings_read_cb read_cb,
        void            *cb_arg,
        void            *param);
 
int settings_load_subtree_direct(
        const char             *subtree,
        settings_load_direct_cb cb,
        void                   *param);
 
int settings_save(void);
 
int settings_save_subtree(const char *subtree);
 
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);
 
/*
 * API for config storage
 */
 
struct settings_store_itf;
 
struct settings_store {
        sys_snode_t cs_next;
        const struct settings_store_itf *cs_itf;
};
struct settings_store {…};
 
struct settings_load_arg {
        const char *subtree;
        settings_load_direct_cb cb;
        void *param;
};
struct settings_load_arg {…};
 
struct settings_store_itf {
        int (*csi_load)(struct settings_store *cs,
                        const struct settings_load_arg *arg);
        ssize_t (*csi_load_one)(struct settings_store *cs, const char *name,
                                char *buf, size_t buf_len);
        ssize_t (*csi_get_val_len)(struct settings_store *cs, const char *name);
        int (*csi_save_start)(struct settings_store *cs);
        int (*csi_save)(struct settings_store *cs, const char *name,
                        const char *value, size_t val_len);
        int (*csi_save_end)(struct settings_store *cs);
        void *(*csi_storage_get)(struct settings_store *cs);
};
struct settings_store_itf {…};
 
void settings_src_register(struct settings_store *cs);
 
void settings_dst_register(struct settings_store *cs);
 
 
/*
 * API for handler lookup
 */
 
struct settings_handler_static *settings_parse_and_lookup(const char *name,
                                                          const char **next);
 
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);
int settings_name_steq(const char *name, const char *key, const char **next);
 
int settings_name_next(const char *name, const char **next);
#ifdef CONFIG_SETTINGS_RUNTIME
 
int settings_runtime_set(const char *name, const void *data, size_t len);
 
int settings_runtime_get(const char *name, void *data, size_t len);
 
int settings_runtime_commit(const char *name);
#endif /* CONFIG_SETTINGS_RUNTIME */
 
int settings_storage_get(void **storage);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_SETTINGS_SETTINGS_H_ */