nvs.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/error>
#include <idfxx/partition>
 
#include <span>
#include <string_view>
#include <vector>
 
typedef uint32_t nvs_handle_t;
typedef int esp_err_t;
 
namespace idfxx {
 
template<typename T>
concept sized_integral =
    std::same_as<T, uint8_t> || std::same_as<T, int8_t> || std::same_as<T, uint16_t> || std::same_as<T, int16_t> ||
    std::same_as<T, uint32_t> || std::same_as<T, int32_t> || std::same_as<T, uint64_t> || std::same_as<T, int64_t>;
class nvs {
public:
    enum class errc : esp_err_t {
        // clang-format off
        not_initialized      = 0x1101,  
        not_found            = 0x1102,  
        type_mismatch        = 0x1103,  
        read_only            = 0x1104,  
        not_enough_space     = 0x1105,  
        invalid_name         = 0x1106,  
        invalid_handle       = 0x1107,  
        remove_failed        = 0x1108,  
        key_too_long         = 0x1109,  
        invalid_state        = 0x110b,  
        invalid_length       = 0x110c,  
        no_free_pages        = 0x110d,  
        value_too_long       = 0x110e,  
        part_not_found       = 0x110f,  
        new_version_found    = 0x1110,  
        xts_encr_failed      = 0x1111,  
        xts_decr_failed      = 0x1112,  
        xts_cfg_failed       = 0x1113,  
        xts_cfg_not_found    = 0x1114,  
        encr_not_supported   = 0x1115,  
        keys_not_initialized = 0x1116,  
        corrupt_key_part     = 0x1117,  
        wrong_encryption     = 0x1119,  
        // clang-format on
    };
 
    class error_category : public std::error_category {
    public:
        [[nodiscard]] const char* name() const noexcept override final;
 
        [[nodiscard]] std::string message(int ec) const override final;
    };
 
    class flash;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit nvs(std::string_view namespace_name, bool read_only = false);
#endif
 
    [[nodiscard]] static result<nvs> make(std::string_view namespace_name, bool read_only = false);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit nvs(const partition& part, std::string_view namespace_name, bool read_only = false);
#endif
 
    [[nodiscard]] static result<nvs>
    make(const partition& part, std::string_view namespace_name, bool read_only = false);
 
    ~nvs();
 
    nvs(const nvs&) = delete;
    nvs& operator=(const nvs&) = delete;
 
    nvs(nvs&& other) noexcept;
 
    nvs& operator=(nvs&& other) noexcept;
 
    [[nodiscard]] bool is_writeable() const { return !_read_only; }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void commit() { unwrap(try_commit()); }
 
    void erase(std::string_view key) { unwrap(try_erase(key)); }
 
    void erase_all() { unwrap(try_erase_all()); }
 
    void set_string(std::string_view key, std::string_view value) { unwrap(try_set_string(key, value)); }
 
    [[nodiscard]] std::string get_string(std::string_view key) { return unwrap(try_get_string(key)); }
 
    void set_blob(std::string_view key, const void* data, size_t length) { unwrap(try_set_blob(key, data, length)); }
 
    void set_blob(std::string_view key, std::span<const uint8_t> data) { unwrap(try_set_blob(key, data)); }
 
    [[nodiscard]] std::vector<uint8_t> get_blob(std::string_view key) { return unwrap(try_get_blob(key)); }
 
    template<typename T>
        requires sized_integral<T>
    void set_value(std::string_view key, T value) {
        unwrap(try_set_value(key, value));
    }
 
    template<typename T>
        requires sized_integral<T>
    [[nodiscard]] T get_value(std::string_view key) {
        return unwrap(try_get_value<T>(key));
    }
#endif
 
    [[nodiscard]] result<void> try_commit();
 
    [[nodiscard]] result<void> try_erase(std::string_view key);
 
    [[nodiscard]] result<void> try_erase_all();
 
    [[nodiscard]] result<void> try_set_string(std::string_view key, std::string_view value);
 
    [[nodiscard]] result<std::string> try_get_string(std::string_view key);
 
    [[nodiscard]] result<void> try_set_blob(std::string_view key, const void* data, size_t length);
 
    [[nodiscard]] result<void> try_set_blob(std::string_view key, std::span<const uint8_t> data);
 
    [[nodiscard]] result<std::vector<uint8_t>> try_get_blob(std::string_view key);
 
    template<typename T>
        requires sized_integral<T>
    [[nodiscard]] result<void> try_set_value(std::string_view key, T value);
 
    template<typename T>
        requires sized_integral<T>
    [[nodiscard]] result<T> try_get_value(std::string_view key);
 
private:
    nvs(nvs_handle_t handle, bool read_only);
 
    nvs_handle_t _handle = 0;
    bool _read_only = false;
};
 
[[nodiscard]] const nvs::error_category& nvs_category() noexcept;
 
[[nodiscard]] inline std::error_code make_error_code(nvs::errc e) noexcept {
    return {std::to_underlying(e), nvs_category()};
}
 
[[nodiscard]] std::unexpected<std::error_code> nvs_error(esp_err_t e);
 
class nvs::flash {
public:
    constexpr static size_t key_size = 32; 
    struct secure_config {
        std::array<uint8_t, key_size> eky; 
        std::array<uint8_t, key_size> tky; 
    };
 
public:
    // Non-instantiable
    flash() = delete;
 
    struct insecure_t {
        explicit insecure_t() = default;
    };
 
    constexpr static insecure_t insecure{};
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    static void init() { unwrap(try_init()); }
 
    static void init(const secure_config& cfg) { unwrap(try_init(cfg)); }
 
    static void init(insecure_t) { unwrap(try_init(insecure)); }
 
    static void init(std::string_view partition_label) { unwrap(try_init(partition_label)); }
 
    static void init(std::string_view partition_label, const secure_config& cfg) {
        unwrap(try_init(partition_label, cfg));
    }
 
    static void init(insecure_t, std::string_view partition_label) { unwrap(try_init(insecure, partition_label)); }
 
    static void init(const partition& part) { unwrap(try_init(part)); }
 
    static void init(const partition& part, const secure_config& cfg) { unwrap(try_init(part, cfg)); }
 
    static void init(insecure_t, const partition& part) { unwrap(try_init(insecure, part)); }
#endif
 
    [[nodiscard]] static result<void> try_init();
 
    [[nodiscard]] static result<void> try_init(const secure_config& cfg);
 
    [[nodiscard]] static result<void> try_init(insecure_t);
 
    [[nodiscard]] static result<void> try_init(std::string_view partition_label);
 
    [[nodiscard]] static result<void> try_init(std::string_view partition_label, const secure_config& cfg);
 
    [[nodiscard]] static result<void> try_init(insecure_t, std::string_view partition_label);
 
    [[nodiscard]] static result<void> try_init(const partition& part);
 
    [[nodiscard]] static result<void> try_init(const partition& part, const secure_config& cfg);
 
    [[nodiscard]] static result<void> try_init(insecure_t, const partition& part);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    static void deinit() { unwrap(try_deinit()); }
 
    static void deinit(std::string_view partition_label) { unwrap(try_deinit(partition_label)); }
#endif
 
    static result<void> try_deinit();
 
    static result<void> try_deinit(std::string_view partition_label);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    static void erase() { unwrap(try_erase()); }
 
    static void erase(std::string_view partition_label) { unwrap(try_erase(partition_label)); }
 
    static void erase(const partition& part) { unwrap(try_erase(part)); }
 
    [[nodiscard]] static secure_config generate_keys(const partition& key_part) {
        return unwrap(try_generate_keys(key_part));
    }
 
    [[nodiscard]] static secure_config read_security_cfg(const partition& key_part) {
        return unwrap(try_read_security_cfg(key_part));
    }
#endif
 
    [[nodiscard]] static result<void> try_erase();
 
    [[nodiscard]] static result<void> try_erase(std::string_view partition_label);
 
    [[nodiscard]] static result<void> try_erase(const partition& part);
 
    [[nodiscard]] static result<secure_config> try_generate_keys(const partition& key_part);
 
    [[nodiscard]] static result<secure_config> try_read_security_cfg(const partition& key_part);
};
 
} // namespace idfxx
 
namespace std {
template<>
struct is_error_code_enum<idfxx::nvs::errc> : true_type {};
} // namespace std