Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-10-02 03:00:34 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs(nvs_flash): correct public API docs for error code

Browse Source 
-align nvs.h / nvs_handle.hpp Doxygen with the implementation: fix return codes
-guard nvs_open against a NULL out_handle
This commit is contained in:
radek.tandler
2026-09-02 14:57:15 +02:00
parent cb709dbf27
commit c3fc203f8a
3 changed files with 84 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/nvs_flash/include/nvs_handle.hpp
+37 -39
View File
@@ -75,16 +75,18 @@ 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_INVALID_HANDLE if the handle has been closed or is NULL
* - 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_KEY_TOO_LONG if the key name is longer than (NVS_KEY_NAME_MAX_SIZE-1) characters
* - 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. The value was written however, and
* 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
* - ESP_ERR_NVS_VALUE_TOO_LONG if the value is too long
* - 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
*/
template<typename T>
@@ -127,10 +129,11 @@ public:
*
* @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_INVALID_HANDLE if the handle has been closed or is NULL
* - 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
* - ESP_ERR_NVS_TYPE_MISMATCH if the type of the stored value doesn't match the requested type
* - 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
*/
template<typename T>
@@ -150,9 +153,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_INVALID_HANDLE if the handle has been closed or is NULL
* - 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_KEY_TOO_LONG if the key name is longer than (NVS_KEY_NAME_MAX_SIZE-1) characters
* - 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
@@ -160,6 +163,8 @@ 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
* - 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
*
* @note compare to nvs_set_blob() in nvs.h
@@ -182,10 +187,12 @@ public:
*
* @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_INVALID_HANDLE if the handle has been closed or is NULL
* - 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_TYPE_MISMATCH if the type of the stored value doesn't match the requested type
* - ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data
* - 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 get_string(const char *key, char* out_str, size_t len) = 0;
@@ -222,11 +229,10 @@ 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 size.
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* @return - ESP_OK if the item with specified type and key exists. Its size will be returned via \c size.
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL
* - 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
* - ESP_ERR_NVS_TYPE_MISMATCH if an item with the requested key exists but has a different 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;
@@ -254,9 +260,11 @@ public:
*
* @return
* - ESP_OK if erase operation was successful
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL
* - 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
* - 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 erase_item(const char* key) = 0;
@@ -271,7 +279,7 @@ public:
*
* @return
* - ESP_OK if erase operation was successful
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - other error codes from the underlying storage driver
*/
@@ -284,7 +292,7 @@ public:
*
* @return
* - ESP_OK if purge operation was successful
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - other error codes from the underlying storage driver
*/
@@ -298,8 +306,7 @@ public:
*
* @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
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL
*/
virtual esp_err_t commit() = 0;
@@ -309,11 +316,13 @@ public:
* @param[out] usedEntries Returns amount of used entries from a namespace on success.
*
* @return
* - ESP_OK if usedEntries was filled with a valid value
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is invalid
* - ESP_OK if the used entry count has been calculated successfully.
* Return param usedEntries will be filled with a valid value.
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL.
* Return param usedEntries will be filled with 0.
* - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized.
* Return param usedEntries will be filled with 0.
* - other error codes from the underlying storage driver.
* - 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;
@@ -363,11 +372,11 @@ protected:
* - 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_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_NVS_KEY_TOO_LONG if the namespace name is longer than (NVS_KEY_NAME_MAX_SIZE-1) characters
* - ESP_ERR_NOT_ALLOWED if the NVS partition is read-only and mode is NVS_READWRITE
* - 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_NO_MEM if memory could not be allocated for the internal structures
* - other error codes from the underlying storage driver
*
* @return unique pointer of an nvs handle on success, an empty unique pointer otherwise
@@ -385,19 +394,8 @@ std::unique_ptr<NVSHandle> open_nvs_handle_from_partition(const char *partition_
*
* @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
* @param[out] err Optional pointer to an esp_err_t result of the open operation. See
* open_nvs_handle_from_partition() for the list of possible error codes.
*
* @return unique pointer of an nvs handle on success, an empty unique pointer otherwise
*/