Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-09-22 13:01:16 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs(nvs_flash): add C++ NVS handle API documentation

Browse Source 
Closes https://github.com/espressif/esp-idf/issues/10283
This commit is contained in:
sonika.rathi
2026-07-22 10:10:26 +02:00
committed by renpeiying
parent 462d942b51
commit 5394a30873
4 changed files with 219 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
components/nvs_flash/include/nvs_handle.hpp
View File

@@ -70,13 +70,14 @@ public:
* For strings, the maximum length (including null character) is
* 4000 bytes, if there is one complete page free for writing.
* This decreases, however, if the free space is fragmented.
* Note that enums loose their type information when stored in NVS. Ensure that the correct
* enum type is used during retrieval with \ref get_item!
* Note that enums lose their type information when stored in NVS. Ensure that the correct
* enum type is used during retrieval with get_item.
*
* @return
* - ESP_OK if value was set successfully
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_KEY_TOO_LONG if key name exceeds the maximum length
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the
* underlying storage to save the value
* - ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash
@@ -84,11 +85,31 @@ public:
* update will be finished after re-initialization of nvs, provided that
* flash operation doesn't fail again.
* - ESP_ERR_NVS_VALUE_TOO_LONG if the string value is too long
* - other error codes from the underlying storage driver
*/
template<typename T>
esp_err_t set_item(const char *key, T value);
virtual
esp_err_t set_string(const char *key, const char* value) = 0;
/**
* @brief set string for given key
*
* @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[in] value The string to set. Maximum length (including null character) is 4000 bytes,
* if there is one complete page free for writing.
*
* @return
* - ESP_OK if value was set successfully
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - ESP_ERR_NVS_KEY_TOO_LONG if key name exceeds the maximum length
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the
* underlying storage to save the value
* - ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash
* write operation has failed
* - ESP_ERR_NVS_VALUE_TOO_LONG if the string value is too long
* - other error codes from the underlying storage driver
*/
virtual esp_err_t set_string(const char *key, const char* value) = 0;
/**
* @brief get value for given key
@@ -102,13 +123,15 @@ public:
* @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param value The output value. All integral types which are declared in ItemType as well as enums
* are allowed. Note however that enums lost their type information when stored in NVS.
* Ensure that the correct enum type is used during retrieval with \ref get_item!
* Ensure that the correct enum type is used during retrieval with get_item.
*
* @return
* - ESP_OK if the value was retrieved successfully
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_TYPE_MISMATCH if the stored value type does not match the requested type
* - ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data
* - other error codes from the underlying storage driver
*/
template<typename T>
esp_err_t get_item(const char *key, T &value);
@@ -127,8 +150,9 @@ public:
*
* @return
* - ESP_OK if value was set successfully
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_KEY_TOO_LONG if key name exceeds the maximum length
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the
* underlying storage to save the value
* - ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash
@@ -136,39 +160,58 @@ public:
* update will be finished after re-initialization of nvs, provided that
* flash operation doesn't fail again.
* - ESP_ERR_NVS_VALUE_TOO_LONG if the value is too long
* - other error codes from the underlying storage driver
*
* @note compare to \ref nvs_set_blob in nvs.h
* @note compare to nvs_set_blob() in nvs.h
*/
virtual esp_err_t set_blob(const char *key, const void* blob, size_t len) = 0;
/**
* @brief get value for given key
* @brief get string value for given key
*
* These functions retrieve the data of an entry, given its key. If key does not
* Retrieves the string data of an entry, given its key. If key does not
* exist, or the requested variable type doesn't match the type which was used
* when setting a value, an error is returned.
*
* In case of any error, out_value is not modified.
*
* Both functions expect out_value to be a pointer to an already allocated variable
* of the given type.
*
* It is suggested that nvs_get/set_str is used for zero-terminated short C strings, and
* nvs_get/set_blob is used for arbitrary data structures and long C strings.
* In case of any error, out_str is not modified.
*
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param out_str/ Pointer to the output value.
* out_blob
* @param[inout] len The length of the output buffer pointed to by out_str/out_blob.
* Use \c get_item_size to query the size of the item beforehand.
* @param[out] out_str Pointer to the output string buffer.
* @param[in] len The length of the output buffer pointed to by out_str.
* Use get_item_size to query the size of the item beforehand.
*
* @return
* - ESP_OK if the value was retrieved successfully
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_TYPE_MISMATCH if the stored value type does not match the requested type
* - ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data
* - other error codes from the underlying storage driver
*/
virtual esp_err_t get_string(const char *key, char* out_str, size_t len) = 0;
/**
* @brief get blob value for given key
*
* Retrieves the binary data of an entry, given its key. If key does not
* exist, or the requested variable type doesn't match the type which was used
* when setting a value, an error is returned.
*
* In case of any error, out_blob is not modified.
*
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[out] out_blob Pointer to the output blob buffer.
* @param[in] len The length of the output buffer pointed to by out_blob.
* Use get_item_size to query the size of the item beforehand.
*
* @return
* - ESP_OK if the value was retrieved successfully
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
* - ESP_ERR_NVS_TYPE_MISMATCH if the stored value type does not match the requested type
* - ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data
* - other error codes from the underlying storage driver
*/
virtual esp_err_t get_blob(const char *key, void* out_blob, size_t len) = 0;
/**
@@ -179,9 +222,12 @@ public:
* @param[out] size Size of the item, if it exists.
* For strings, this size includes the zero terminator.
*
* @return - ESP_OK if the item with specified type and key exists. Its size will be returned via \c size.
* - ESP_ERR_NVS_NOT_FOUND if an item with the requested key and type doesn't exist or any other
* error occurs.
* @return
* - ESP_OK if the item with specified type and key exists. Its size will be returned via size.
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_NOT_FOUND if an item with the requested key and type doesn't exist
* - ESP_ERR_NVS_TYPE_MISMATCH if the stored value type does not match the requested type
* - other error codes from the underlying storage driver
*/
virtual esp_err_t get_item_size(ItemType datatype, const char *key, size_t &size) = 0;
@@ -189,61 +235,112 @@ public:
* @brief Checks whether key exists and optionally returns also data type of associated entry.
*
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[out] nvstype Nvs data type to of entry, if it exists.
* @param[out] nvstype Nvs data type of entry, if it exists.
*
* @return - ESP_OK if NVS entry for key provided was found. Data type will be returned via \c nvstype.
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist.
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL.
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled).
* - other error codes from the underlying storage driver.
* @return
* - ESP_OK if NVS entry for key provided was found. Data type will be returned via nvstype.
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - other error codes from the underlying storage driver
*/
virtual esp_err_t find_key(const char* key, nvs_type_t &nvstype) = 0;
/**
* @brief Erases an entry.
*
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
*
* @return
* - ESP_OK if erase operation was successful
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
* - other error codes from the underlying storage driver
*/
virtual esp_err_t erase_item(const char* key) = 0;
/**
* Erases all entries in the scope of this handle. The scope may vary, depending on the implementation.
* @brief Erases all entries in the scope of this handle.
*
* @not If you want to erase the whole nvs flash (partition), refer to \ref
* The scope may vary, depending on the implementation (typically the opened namespace).
*
* @note If you want to erase the whole NVS flash partition, use nvs_flash_erase() /
* nvs_flash_erase_partition() instead.
*
* @return
* - ESP_OK if erase operation was successful
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - other error codes from the underlying storage driver
*/
virtual esp_err_t erase_all() = 0;
/**
* Purges all erased entries in the scope of this handle. The scope may vary, depending on the implementation.
* @brief Purges all erased entries in the scope of this handle.
*
* The scope may vary, depending on the implementation.
*
* @return
* - ESP_OK if purge operation was successful
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - other error codes from the underlying storage driver
*/
virtual esp_err_t purge_all() = 0;
/**
* Commits all changes done through this handle so far.
* @brief Commits all changes done through this handle so far.
*
* Currently, NVS writes to storage right after the set and get functions,
* but this is not guaranteed.
*
* @return
* - ESP_OK if commit was successful
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - other error codes from the underlying storage driver
*/
virtual esp_err_t commit() = 0;
/**
* @brief Calculate all entries in the scope of the handle.
*
* @param[out] used_entries Returns amount of used entries from a namespace on success.
*
* @param[out] usedEntries Returns amount of used entries from a namespace on success.
*
* @return
* - ESP_OK if the changes have been written successfully.
* Return param used_entries will be filled valid value.
* - ESP_OK if usedEntries was filled with a valid value
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized.
* Return param used_entries will be filled 0.
* - ESP_ERR_INVALID_ARG if nvs_stats equal to NULL.
* - Other error codes from the underlying storage driver.
* Return param used_entries will be filled 0.
* Return param usedEntries will be filled with 0.
* - other error codes from the underlying storage driver.
* Return param usedEntries will be filled with 0.
*/
virtual esp_err_t get_used_entry_count(size_t& usedEntries) = 0;
protected:
/**
* @brief Set an item of a given datatype.
*
* @param[in] datatype Item data type.
* @param[in] key Key name.
* @param[in] data Pointer to the value to store.
* @param[in] dataSize Size of the value in bytes.
*
* @return esp_err_t result codes matching set_item / set_blob.
*/
virtual esp_err_t set_typed_item(ItemType datatype, const char *key, const void* data, size_t dataSize) = 0;
/**
* @brief Get an item of a given datatype.
*
* @param[in] datatype Item data type.
* @param[in] key Key name.
* @param[out] data Pointer to the output buffer.
* @param[in] dataSize Size of the output buffer in bytes.
*
* @return esp_err_t result codes matching get_item / get_blob.
*/
virtual esp_err_t get_typed_item(ItemType datatype, const char *key, void* data, size_t dataSize) = 0;
};
@@ -253,16 +350,23 @@ protected:
* The handle is automatically closed on destruction. The scope of the handle is the namespace ns_name
* in a particular partition partition_name.
* The parameters partition_name, ns_name and open_mode have the same meaning and restrictions as the parameters
* part_name, name and open_mode in \ref nvs_open_from_partition, respectively.
* part_name, namespace_name and open_mode in nvs_open_from_partition(), respectively.
*
* @param err an optional pointer to an esp_err_t result of the open operation, having the same meaning as the return
* value in \ref nvs_open_from_partition:
* @param[in] partition_name Label of the NVS partition to open.
* @param[in] ns_name Namespace name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters.
* @param[in] open_mode NVS_READONLY, NVS_READWRITE, or NVS_READWRITE_PURGE.
* @param[out] err Optional pointer to an esp_err_t result of the open operation, having the same meaning
* as the return value of nvs_open_from_partition():
* - ESP_OK if storage handle was opened successfully
* - ESP_ERR_INVALID_ARG if partition_name or ns_name is NULL
* - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized
* - ESP_ERR_NVS_PART_NOT_FOUND if the partition with label "nvs" is not found
* - ESP_ERR_NVS_NOT_FOUND id namespace doesn't exist yet and
* - ESP_ERR_NVS_PART_NOT_FOUND if the partition with the specified name is not found
* - ESP_ERR_NVS_NOT_FOUND if namespace doesn't exist yet and
* mode is NVS_READONLY
* - ESP_ERR_NVS_INVALID_NAME if namespace name doesn't satisfy constraints
* - ESP_ERR_NVS_KEY_TOO_LONG if namespace name exceeds the maximum length
* - ESP_ERR_NO_MEM if memory could not be allocated for the internal structures
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is no space for a new entry or there are too many different
* namespaces (maximum allowed different namespaces: 254)
* - ESP_ERR_NOT_ALLOWED if the NVS partition is read-only and mode is NVS_READWRITE
* - other error codes from the underlying storage driver
*
@@ -274,8 +378,28 @@ std::unique_ptr<NVSHandle> open_nvs_handle_from_partition(const char *partition_
esp_err_t *err = nullptr);
/**
* @brief This function does the same as \ref open_nvs_handle_from_partition but uses the default nvs partition
* @brief Open NVS handle from the default NVS partition.
*
* This function does the same as open_nvs_handle_from_partition() but uses the default nvs partition
* instead of a partition_name parameter.
*
* @param[in] ns_name Namespace name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters.
* @param[in] open_mode NVS_READONLY, NVS_READWRITE, or NVS_READWRITE_PURGE.
* @param[out] err Optional pointer to an esp_err_t result of the open operation:
* - ESP_OK if storage handle was opened successfully
* - ESP_ERR_INVALID_ARG if ns_name is NULL
* - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized
* - ESP_ERR_NVS_PART_NOT_FOUND if the partition with label "nvs" is not found
* - ESP_ERR_NVS_NOT_FOUND if namespace doesn't exist yet and
* mode is NVS_READONLY
* - ESP_ERR_NVS_KEY_TOO_LONG if namespace name exceeds the maximum length
* - ESP_ERR_NO_MEM if memory could not be allocated for the internal structures
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is no space for a new entry or there are too many different
* namespaces (maximum allowed different namespaces: 254)
* - ESP_ERR_NOT_ALLOWED if the NVS partition is read-only and mode is NVS_READWRITE
* - other error codes from the underlying storage driver
*
* @return unique pointer of an nvs handle on success, an empty unique pointer otherwise
*/
std::unique_ptr<NVSHandle> open_nvs_handle(const char *ns_name,
nvs_open_mode_t open_mode,

1
docs/doxygen/Doxyfile
View File

@@ -340,6 +340,7 @@ INPUT = \
$(PROJECT_PATH)/components/mbedtls/port/psa_driver/include/psa_crypto_driver_esp_aes_contexts.h \
$(PROJECT_PATH)/components/nvs_flash/include/nvs_flash.h \
$(PROJECT_PATH)/components/nvs_flash/include/nvs.h \
$(PROJECT_PATH)/components/nvs_flash/include/nvs_handle.hpp \
$(PROJECT_PATH)/components/nvs_flash/include/nvs_bootloader.h \
$(PROJECT_PATH)/components/nvs_sec_provider/include/nvs_sec_provider.h \
$(PROJECT_PATH)/components/openthread/include/esp_openthread_border_router.h \

22
docs/en/api-reference/storage/nvs_flash.rst
View File

@@ -86,6 +86,22 @@ The open mode parameter controls the access level and security behavior:
Namespaces with the same name in different NVS partitions are considered as separate namespaces.
C++ API
^^^^^^^
In addition to the C API described above, NVS provides a C++ class interface in :component_file:`nvs_flash/include/nvs_handle.hpp` (namespace ``nvs``).
Use ``nvs::open_nvs_handle()`` or ``nvs::open_nvs_handle_from_partition()`` to open a namespace. These functions return a ``std::unique_ptr<nvs::NVSHandle>``. The handle is closed automatically when the unique pointer is destroyed (RAII), so there is no need to call a separate close function.
``nvs::NVSHandle`` provides methods that mirror the C API, including:
- ``set_item`` / ``get_item`` — typed get/set for integral, floating-point, and enum types
- ``set_string`` / ``get_string`` — string values
- ``set_blob`` / ``get_blob`` — binary blob values
- ``commit``, ``erase_item``, ``erase_all``, ``purge_all``, ``find_key``, and related helpers
Open modes (``NVS_READONLY``, ``NVS_READWRITE``, ``NVS_READWRITE_PURGE``) and key/namespace constraints are the same as for the C API. See the :ref:`API Reference <nvs-api-reference>` below for full class and function documentation, and :example:`storage/nvs/nvs_rw_value_cxx` for a complete example.
NVS Iterators
^^^^^^^^^^^^^
@@ -264,7 +280,7 @@ You can find code examples in the :example:`storage/nvs` directory of ESP-IDF ex
:example:`storage/nvs/nvs_rw_value_cxx`
This example does exactly the same as :example:`storage/nvs/nvs_rw_value`, except that it uses the C++ NVS handle class.
This example does exactly the same as :example:`storage/nvs/nvs_rw_value`, except that it uses the C++ NVS handle class (``nvs::NVSHandle`` via ``nvs::open_nvs_handle()``).
:example:`storage/nvs/nvs_statistics`
@@ -552,9 +568,13 @@ At build time the mode NVS will use for accessing its underlying storage can be
.. _nvs-api-reference:
API Reference
-------------
.. include-build-file:: inc/nvs_flash.inc
.. include-build-file:: inc/nvs.inc
.. include-build-file:: inc/nvs_handle.inc

22
docs/zh_CN/api-reference/storage/nvs_flash.rst
View File

@@ -86,6 +86,22 @@ open mode 参数控制访问级别和安全行为：
在不同的 NVS 分区中，同名的命名空间被视为相互独立的命名空间。
C++ API
^^^^^^^
除上文所述的 C API 外，NVS 还在 :component_file:`nvs_flash/include/nvs_handle.hpp` 中提供了 C++ 类接口（命名空间 ``nvs``）。
使用 ``nvs::open_nvs_handle()`` 或 ``nvs::open_nvs_handle_from_partition()`` 打开命名空间。这些函数返回 ``std::unique_ptr<nvs::NVSHandle>``。当该智能指针被销毁时，句柄会自动关闭（RAII），因此无需另行调用关闭函数。
``nvs::NVSHandle`` 提供与 C API 对应的方法，包括：
- ``set_item`` / ``get_item`` — 面向整型、浮点型和枚举类型的类型化读写
- ``set_string`` / ``get_string`` — 字符串值
- ``set_blob`` / ``get_blob`` — 二进制 blob 值
- ``commit``、``erase_item``、``erase_all``、``purge_all``、``find_key`` 及相关辅助方法
打开模式（``NVS_READONLY``、``NVS_READWRITE``、``NVS_READWRITE_PURGE``）以及键名/命名空间约束与 C API 相同。完整的类与函数说明见下文 :ref:`API 参考 <nvs-api-reference>`，完整示例见 :example:`storage/nvs/nvs_rw_value_cxx`。
NVS 迭代器
^^^^^^^^^^^^^
@@ -264,7 +280,7 @@ ESP-IDF :example:`storage/nvs` 目录下提供了数个代码示例：
:example:`storage/nvs/nvs_rw_value_cxx`
这个例子与 :example:`storage/nvs/nvs_rw_value` 完全一样，只是使用了 C++ 的 NVS 句柄类。
这个例子与 :example:`storage/nvs/nvs_rw_value` 完全一样，只是使用了 C++ 的 NVS 句柄类（通过 ``nvs::open_nvs_handle()`` 获取 ``nvs::NVSHandle``）。
:example:`storage/nvs/nvs_statistics`
@@ -552,9 +568,13 @@ NVS 正常运行所需的默认最小空间为 12 KiB (``0x3000``)，即至少
.. _nvs-api-reference:
API 参考
-------------
.. include-build-file:: inc/nvs_flash.inc
.. include-build-file:: inc/nvs.inc
.. include-build-file:: inc/nvs_handle.inc