Outline ![]()
Files ![]()
loading (4/5)...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
#ifndef NVS_HANDLE_HPP_
#define NVS_HANDLE_HPP_
#include <string>
#include <memory>
#include <type_traits>
#include "nvs.h"
namespace nvs {
#if defined(SEGGER_H) && defined(GLOBAL_H)
NVS_GUARD_SYSVIEW_MACRO_EXPANSION_PUSH();
#undef U8
#undef I8
#undef U16
#undef I16
#undef U32
#undef I32
#undef U64
#undef I64
#endif
/**
* The possible blob types. This is a helper definition for template functions.
*/
enum class ItemType : uint8_t {
U8 = NVS_TYPE_U8,
I8 = NVS_TYPE_I8,
U16 = NVS_TYPE_U16,
I16 = NVS_TYPE_I16,
U32 = NVS_TYPE_U32,
I32 = NVS_TYPE_I32,
U64 = NVS_TYPE_U64,
I64 = NVS_TYPE_I64,
SZ = NVS_TYPE_STR,
BLOB = 0x41,
BLOB_DATA = NVS_TYPE_BLOB,
BLOB_IDX = 0x48,
ANY = NVS_TYPE_ANY
};
#if defined(SEGGER_H) && defined(GLOBAL_H)
NVS_GUARD_SYSVIEW_MACRO_EXPANSION_POP();
#endif
/**
* @brief A handle allowing nvs-entry related operations on the NVS.
*
* @note The scope of this handle may vary depending on the implementation, but normally would be the namespace of
* a particular partition. Outside that scope, nvs entries can't be accessed/altered.
*/
class NVSHandle {
public:
virtual ~NVSHandle() { }
/**
* @brief set value for given key
*
* Sets value for key. Note that physical storage will not be updated until nvs_commit function is called.
*
* @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, 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!
*
* @return
* - ESP_OK if value was set successfully
* - 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_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
*/
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 get value for given key
*
* These functions retrieve value for the key, given its name. 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.
*
* @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!
*
* @return
* - ESP_OK if the value was retrieved successfully
* - 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_INVALID_LENGTH if length is not sufficient to store data
*/
template<typename T>
esp_err_t get_item(const char *key, T &value);
/**
* @brief set variable length binary value for given key
*
* This family of functions set value for the key, given its name. Note that
* actual storage will not be updated until nvs_commit function is called.
*
* @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[in] blob The blob value to set.
* @param[in] len length of binary value to set, in bytes; Maximum length is
* 508000 bytes or (97.6% of the partition size - 4000) bytes
* whichever is lower.
*
* @return
* - ESP_OK if value was set successfully
* - 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_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 value is too long
*
* @note compare to \ref 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
*
* These functions retrieve the 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.
*
* @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.
*
* @return
* - ESP_OK if the value was retrieved successfully
* - 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_INVALID_LENGTH if length is not sufficient to store data
*/
virtual esp_err_t get_string(const char *key, char* out_str, size_t len) = 0;
virtual esp_err_t get_blob(const char *key, void* out_blob, size_t len) = 0;
/**
* @brief Look up the size of an entry's data.
*
* @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;
/**
* @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.
*
* @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.
*/
virtual esp_err_t find_key(const char* key, nvs_type_t &nvstype) = 0;
/**
* @brief Erases an entry.
*/
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.
*
* @not If you want to erase the whole nvs flash (partition), refer to \ref
*/
virtual esp_err_t erase_all() = 0;
/**
* 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;
/**
* @brief Calculate all entries in the scope of the handle.
*
* @param[out] used_entries 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_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.
*/
virtual esp_err_t get_used_entry_count(size_t& usedEntries) = 0;
protected:
virtual esp_err_t set_typed_item(ItemType datatype, const char *key, const void* data, size_t dataSize) = 0;
virtual esp_err_t get_typed_item(ItemType datatype, const char *key, void* data, size_t dataSize) = 0;
};
/**
* @brief Opens non-volatile storage and returns a handle object.
*
* 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.
*
* @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:
* - ESP_OK if storage handle was opened successfully
* - 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
* mode is NVS_READONLY
* - ESP_ERR_NVS_INVALID_NAME if namespace name doesn't satisfy constraints
* - 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_from_partition(const char *partition_name,
const char *ns_name,
nvs_open_mode_t open_mode,
esp_err_t *err = nullptr);
/**
* @brief This function does the same as \ref open_nvs_handle_from_partition but uses the default nvs partition
* instead of a partition_name parameter.
*/
std::unique_ptr<NVSHandle> open_nvs_handle(const char *ns_name,
nvs_open_mode_t open_mode,
esp_err_t *err = nullptr);
// Helper functions for template usage
/**
* Help to translate all integral types into ItemType.
*/
template<typename T, typename std::enable_if<std::is_integral<T>::value, void*>::type = nullptr>
constexpr ItemType itemTypeOf()
{
return static_cast<ItemType>(((std::is_signed<T>::value)?0x10:0x00) | sizeof(T));
}
/**
* Help to translate all enum types into integral ItemType.
*/
template<typename T, typename std::enable_if<std::is_enum<T>::value, int>::type = 0>
constexpr ItemType itemTypeOf()
{
return static_cast<ItemType>(((std::is_signed<T>::value)?0x10:0x00) | sizeof(T));
}
template<typename T>
constexpr ItemType itemTypeOf(const T&)
{
return itemTypeOf<T>();
}
// Template Implementations
template<typename T>
esp_err_t NVSHandle::set_item(const char *key, T value) {
return set_typed_item(itemTypeOf(value), key, &value, sizeof(value));
}
template<typename T>
esp_err_t NVSHandle::get_item(const char *key, T &value) {
return get_typed_item(itemTypeOf(value), key, &value, sizeof(value));
}
} // nvs
#endif // NVS_HANDLE_HPP_
Details ![]()
Show: from Types: Columns: ![]( "Show Project Names")
![]( "Show Locations")
![]( "Show Referring Symbols")
![]( "Show Scope")
This file uses the notable symbols shown below. Click anywhere in the file to view more details.