NVS Helper

[English]

  • 公共头文件： #include "brookesia/service_helper/nvs.hpp"

概述

本页用于查看 NVS helper 的原始 Doxygen API，包括公共类型、枚举、方法与相关宏定义。

API 参考

Header File

Classes

class NVS : public esp_brookesia::service::helper::Base<NVS>

Helper schema definitions for the NVS service.

Public Types

enum class ValueType

They are used as parameter and return types for functions and events. Users can access or modify these types via serialization and deserialization.

Values:

enumerator Bool
enumerator Int
enumerator String
enumerator Max
enum class FunctionId

NVS service function identifiers.

Values:

enumerator List
enumerator Set
enumerator Get
enumerator Erase
enumerator Max
enum class EventId

NVS service event identifiers.

Values:

enumerator Max
enum class FunctionListParam

Parameter keys for FunctionId::List.

Values:

enumerator Nspace
enum class FunctionSetParam

Parameter keys for FunctionId::Set.

Values:

enumerator Nspace
enumerator KeyValuePairs
enum class FunctionGetParam

Parameter keys for FunctionId::Get.

Values:

enumerator Nspace
enumerator Keys
enum class FunctionEraseParam

Parameter keys for FunctionId::Erase.

Values:

enumerator Nspace
enumerator Keys
using Value = std::variant<bool, int32_t, std::string>

Value type stored in NVS entries.

using KeyValueMap = std::map<std::string, Value>

Key-value mapping payload for batch set/get operations.

Public Static Functions

static inline constexpr std::string_view get_name()

Service name used by ServiceManager.

返回

std::string_view Stable service name.

static inline std::span<const FunctionSchema> get_function_schemas()

Get function schemas exported by NVS service.

返回

std::span<const FunctionSchema> Static function schema span.

static inline std::span<const EventSchema> get_event_schemas()

Get event schemas exported by NVS service.

返回

std::span<const EventSchema> Empty span because NVS has no events.

template<typename T>
static inline std::expected<void, std::string> save_key_value(const std::string &nspace, const std::string &key, const T &value, uint32_t timeout_ms = DEFAULT_TIMEOUT_MS)

Save key-value pairs to the NVS namespace.

Direct Storage (No Serialization):

  • bool: Stored directly as JSON boolean value (true/false)

  • int32_t: Stored directly as JSON number (int64_t in JSON)

  • Integer types with size <= 32 bits (int8_t, uint8_t, int16_t, uint16_t, char, short, etc.): Converted to int32_t and stored as JSON number for optimal performance

Serialized Storage:

  • Integer types with size > 32 bits (int64_t, uint64_t, long long, etc.): Serialized to JSON string using BROOKESIA_DESCRIBE_JSON_SERIALIZE

  • Floating point types (float, double): Serialized to JSON string using BROOKESIA_DESCRIBE_JSON_SERIALIZE

  • String types (std::string, const char*): Serialized to JSON string using BROOKESIA_DESCRIBE_JSON_SERIALIZE

  • Complex types (std::vector, std::map, custom structs, etc.): Serialized to JSON string using BROOKESIA_DESCRIBE_JSON_SERIALIZE

备注

The storage method depends on the type T:

模板参数

T – The type of the value to save

参数

  • nspace – The namespace of the key-value pairs to save

  • key – The key of the key-value pair to save

  • value – The value of the key-value pair to save

  • timeout_ms – The timeout in milliseconds

返回

std::expected<void, std::string> The result of the operation

template<typename T>
static inline std::expected<T, std::string> get_key_value(const std::string &nspace, const std::string &key, uint32_t timeout_ms = DEFAULT_TIMEOUT_MS)

Get key-value pair from the NVS namespace.

Direct Retrieval (No Deserialization):

  • bool: Retrieved directly from JSON boolean value

  • int32_t: Retrieved directly from JSON number

  • Integer types with size <= 32 bits (int8_t, uint8_t, int16_t, uint16_t, char, short, etc.): Retrieved directly from JSON number and converted to the target integer type

Deserialized Retrieval:

  • Integer types with size > 32 bits (int64_t, uint64_t, long long, etc.): Retrieved directly from JSON string and deserialized to the target integer type

  • Floating point types (float, double): Retrieved directly from JSON string and deserialized to the target floating point type

  • String types (std::string): Retrieved directly from JSON string and deserialized to the target string type

  • Complex types (std::vector, std::map, custom structs, etc.): Retrieved directly from JSON string and deserialized to the target complex type

备注

The retrieval method depends on the type T and matches the storage method used in save_key_value():

模板参数

T – The type of the value to retrieve

参数

  • nspace – The namespace of the key-value pair to retrieve

  • key – The key of the key-value pair to retrieve

  • timeout_ms – The timeout in milliseconds

返回

std::expected<T, std::string> The retrieved value or error message

static inline std::expected<void, std::string> erase_keys(const std::string &nspace, const std::vector<std::string> &keys = {}, uint32_t timeout_ms = DEFAULT_TIMEOUT_MS)

Erase key-value pairs from the NVS namespace.

参数

  • nspace – The namespace of the key-value pairs to erase

  • keys – The keys of the key-value pairs to erase, optional. If not provided or empty, all key-value pairs in the namespace will be erased

  • timeout_ms – The timeout in milliseconds

返回

std::expected<void, std::string> The result of the operation

Public Static Attributes

static constexpr uint32_t DEFAULT_TIMEOUT_MS = BROOKESIA_SERVICE_MANAGER_DEFAULT_CALL_FUNCTION_TIMEOUT_MS

Default timeout for synchronous NVS helper calls.

struct EntryInfo

Metadata for one entry in an NVS namespace.

Public Members

std::string nspace

Namespace name

std::string key

Entry key

ValueType type

Entry value type