nvs_entry_find, nvs_entry_next don't return proper error codes for differentiating between not found and internal errors (IDFGH-6149)

[Emill]

Is your feature request related to a problem? Please describe.

The nvs iteration API looks very different from the rest of the nvs API. After reading #129, I now understand that this API was added later, so probably that's the reason it looks so different. The new API doesn't operate on handles and doesn't return proper error codes for the various situations when not a valid iterator could be returned.

The issue with this new API is that NULL is returned regardless of the error. According to the documentation, an iterator will be returned if there is a matching entry, and NULL if no entry satisfying criteria was found. But this is kind of a lie. In case, e.g. a malloc operation failed due to out of memory, flash read failed etc., NULL will be returned as well. This makes it impossible to differentiate when there actually are no entries found, and when some internal operation failed for other reasons. In case of out of memory, I as an application developer would try to free some other application memory and then try the nvs operation again, but now this is not possible.

Describe the solution you'd like

A different API with proper error codes so I can know for sure if no entries exist or some other error occurred. Proposedly, the API should also use nvs_handle_t instead of taking namespace as a string to be consistent with the rest of the API. The user probably wants to have such an opened handle anyway to later read the values being iterating over.

[0xjakob]

@Emill It's a nice suggestion, thank you for that! The problem is that we can't easily change a public API which is used already. We may change this during transition to IDF v5.0 but I can't promise this for 100%. We'll keep you updated on this issue.

[0xjakob]

@Emill We are about to change the NVS iterator API now.
The new NVS iterator programming patter would look like this:

nvs_iterator_t it = nullptr;
esp_err_t res = nvs_entry_find(<nvs_partition_name>, <namespace>, NVS_TYPE_ANY, &it);
while(res == ESP_OK) {
    nvs_entry_info_t info;
    nvs_entry_info(it, &info); // Can omit error check if parameters are guaranteed to be non-NULL
    printf("key '%s', type '%d' \n", info.key, info.type);
    res = nvs_entry_next(&it);
}

The changed functions would look like this:

esp_err_t nvs_entry_find(const char *part_name,
        const char *namespace_name,
        nvs_type_t type,
        nvs_iterator_t *output_iterator);

esp_err_t nvs_entry_next(nvs_iterator_t *it);

esp_err_t nvs_entry_info(const nvs_iterator_t iterator, nvs_entry_info_t *out_info);

Feel free to try the following patch:
0001-refactor-nvs-New-interface-for-iterator-functions.zip