Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-10-01 18:50:34 +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-08-13 15:42:18 +08: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
components/nvs_flash/include/nvs_handle.hpp
+176 -52
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,