alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-10-28 04:05:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

[doc]: NVS documentation updates

Browse Source 
* Move nvs flash README to common doc directory
* correct markup of functions and types in text
  from old README
* Better comment of nvs_get_used_entry_count()
* Mention C++ example in API reference
* Used target instead of hard code ESP32
* Note that strings can only span one page
* Reflect that item types have been moved
* Some clarification about nvs_commit()
* Improved reference to the ESP Partition API
* fixed little mistake in documenting-code.rst
* Change of nvs_open_from_part() to
  nvs_open_from_partition() reflected in docs
* Corrected documentation of
  NVSHandle::get_string(), NVSHandle::get_blob()
  and NVSHandle::get_item_size().

* Closes DOC-165
* Closes IDF-1563
* Closes IDF-859
* Closes https://github.com/espressif/esp-idf/issues/6123
This commit is contained in:
Jakob Hasse
2021-01-19 16:15:40 +08:00
parent 98c20ce417
commit 5395f451a2
7 changed files with 807 additions and 680 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -47,7 +47,8 @@ public:
* @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[in] value The value to set. Allowed types are the ones declared in ItemType as well as enums.
* For strings, the maximum length (including null character) is
* 4000 bytes.
* 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!
*
@@ -131,15 +132,14 @@ public:
* 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 C strings, and
* nvs_get/set_blob used for arbitrary data structures.
* 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.
*
* @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @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] length A non-zero pointer to the variable holding the length of out_value.
* It will be set to the actual length of the value
* written. For nvs_get_str this includes the zero terminator.
* @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.
*
* @return
* - ESP_OK if the value was retrieved successfully
@@ -151,9 +151,16 @@ public:
virtual esp_err_t get_blob(const char *key, void* out_blob, size_t len) = 0;
/**
* @brief Looks up the size of an entry's data.
* @brief Look up the size of an entry's data.
*
* For strings, this size includes the zero terminator.
* @param[in] datatype Data type to search for.
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @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.
*/
virtual esp_err_t get_item_size(ItemType datatype, const char *key, size_t &size) = 0;
@@ -171,6 +178,8 @@ public:
/**
* 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.
*/
virtual esp_err_t commit() = 0;