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_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));
};

 
#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,                                                               \
        }

#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);
 
#if defined(CONFIG_SETTINGS_SAVE_SINGLE_SUBTREE_WITHOUT_MODIFICATION) || defined(__DOXYGEN__)
int settings_save_subtree_or_single_without_modification(const char *name,
                                                         bool save_if_subtree,
                                                         bool save_if_single_setting);
#endif


 
/*
 * 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_load_arg {
        const char *subtree;
        settings_load_direct_cb cb;
        void *param;
};

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);
};

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_ */