feedc0de/esp-idf
1
0
Fork 0
forked from espressif/esp-idf
Code Pull Requests Activity

refactor (nvs)!: New interface for iterator functions

Browse Source 
Closes https://github.com/espressif/esp-idf/issues/7826

* nvs_entry_find(), nvs_entry_next() and nvs_entry_info()
  return error codes now
* nvs_entry_find() and nvs_entry_next() access/modify iterator via
  parameters, instead of returning an new iterator.

Added appropriate documentation in Chinese and English
This commit is contained in:
Jakob Hasse
2022-05-11 18:49:55 +08:00
parent 769bc9b2d2
commit ad184e979a
9 changed files with 322 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -55,11 +55,12 @@ Iterators allow to list key-value pairs stored in NVS, based on specified partit
There are the following functions available:
- :cpp:func:`nvs_entry_find` returns an opaque handle, which is used in subsequent calls to the :cpp:func:`nvs_entry_next` and :cpp:func:`nvs_entry_info` functions.
- :cpp:func:`nvs_entry_next` returns iterator to the next key-value pair.
- :cpp:func:`nvs_entry_find` creates an opaque handle, which is used in subsequent calls to the :cpp:func:`nvs_entry_next` and :cpp:func:`nvs_entry_info` functions.
- :cpp:func:`nvs_entry_next` advances an iterator to the next key-value pair.
- :cpp:func:`nvs_entry_info` returns information about each key-value pair
If none or no other key-value pair was found for given criteria, :cpp:func:`nvs_entry_find` and :cpp:func:`nvs_entry_next` return NULL. In that case, the iterator does not have to be released. If the iterator is no longer needed, you can release it by using the function :cpp:func:`nvs_release_iterator`.
In general, all iterators obtained via :cpp:func:`nvs_entry_find` have to be released using :cpp:func:`nvs_release_iterator`, which also tolerates ``NULL`` iterators.
:cpp:func:`nvs_entry_find` and :cpp:func:`nvs_entry_next` will set the given iterator to ``NULL`` or a valid iterator in all cases except a parameter error occured (i.e., return ``ESP_ERR_NVS_NOT_FOUND``). In case of a parameter error, the given iterator will not be modified. Hence, it is best practice to initialize the iterator to ``NULL`` before calling :cpp:func:`nvs_entry_find` to avoid complicated error checking before releasing the iterator.
Security, tampering, and robustness