Outline ![]()
Files ![]()
loading...
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
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
/*
* SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef ESP_NVS_H
#define ESP_NVS_H
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include "esp_attr.h"
#include "esp_err.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* Opaque pointer type representing non-volatile storage handle
*/
typedef uint32_t nvs_handle_t;
/*
* Pre-IDF V4.0 uses nvs_handle, so leaving the original typedef here for compatibility.
*/
typedef nvs_handle_t nvs_handle IDF_DEPRECATED("Replace with nvs_handle_t");
#define ESP_ERR_NVS_BASE 0x1100 /*!< Starting number of error codes */
#define ESP_ERR_NVS_NOT_INITIALIZED (ESP_ERR_NVS_BASE + 0x01) /*!< The storage driver is not initialized */
#define ESP_ERR_NVS_NOT_FOUND (ESP_ERR_NVS_BASE + 0x02) /*!< A requested entry couldn't be found or namespace doesn’t exist yet and mode is NVS_READONLY */
#define ESP_ERR_NVS_TYPE_MISMATCH (ESP_ERR_NVS_BASE + 0x03) /*!< The type of set or get operation doesn't match the type of value stored in NVS */
#define ESP_ERR_NVS_READ_ONLY (ESP_ERR_NVS_BASE + 0x04) /*!< Storage handle was opened as read only */
#define ESP_ERR_NVS_NOT_ENOUGH_SPACE (ESP_ERR_NVS_BASE + 0x05) /*!< There is not enough space in the underlying storage to save the value */
#define ESP_ERR_NVS_INVALID_NAME (ESP_ERR_NVS_BASE + 0x06) /*!< Namespace name doesn’t satisfy constraints */
#define ESP_ERR_NVS_INVALID_HANDLE (ESP_ERR_NVS_BASE + 0x07) /*!< Handle has been closed or is NULL */
#define ESP_ERR_NVS_REMOVE_FAILED (ESP_ERR_NVS_BASE + 0x08) /*!< 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. */
#define ESP_ERR_NVS_KEY_TOO_LONG (ESP_ERR_NVS_BASE + 0x09) /*!< Key name is too long */
#define ESP_ERR_NVS_PAGE_FULL (ESP_ERR_NVS_BASE + 0x0a) /*!< Internal error; never returned by nvs API functions */
#define ESP_ERR_NVS_INVALID_STATE (ESP_ERR_NVS_BASE + 0x0b) /*!< NVS is in an inconsistent state due to a previous error. Call nvs_flash_init and nvs_open again, then retry. */
#define ESP_ERR_NVS_INVALID_LENGTH (ESP_ERR_NVS_BASE + 0x0c) /*!< String or blob length is not sufficient to store data */
#define ESP_ERR_NVS_NO_FREE_PAGES (ESP_ERR_NVS_BASE + 0x0d) /*!< NVS partition doesn't contain any empty pages. This may happen if NVS partition was truncated. Erase the whole partition and call nvs_flash_init again. */
#define ESP_ERR_NVS_VALUE_TOO_LONG (ESP_ERR_NVS_BASE + 0x0e) /*!< Value doesn't fit into the entry or string or blob length is longer than supported by the implementation */
#define ESP_ERR_NVS_PART_NOT_FOUND (ESP_ERR_NVS_BASE + 0x0f) /*!< Partition with specified name is not found in the partition table */
#define ESP_ERR_NVS_NEW_VERSION_FOUND (ESP_ERR_NVS_BASE + 0x10) /*!< NVS partition contains data in new format and cannot be recognized by this version of code */
#define ESP_ERR_NVS_XTS_ENCR_FAILED (ESP_ERR_NVS_BASE + 0x11) /*!< XTS encryption failed while writing NVS entry */
#define ESP_ERR_NVS_XTS_DECR_FAILED (ESP_ERR_NVS_BASE + 0x12) /*!< XTS decryption failed while reading NVS entry */
#define ESP_ERR_NVS_XTS_CFG_FAILED (ESP_ERR_NVS_BASE + 0x13) /*!< XTS configuration setting failed */
#define ESP_ERR_NVS_XTS_CFG_NOT_FOUND (ESP_ERR_NVS_BASE + 0x14) /*!< XTS configuration not found */
#define ESP_ERR_NVS_ENCR_NOT_SUPPORTED (ESP_ERR_NVS_BASE + 0x15) /*!< NVS encryption is not supported in this version */
#define ESP_ERR_NVS_KEYS_NOT_INITIALIZED (ESP_ERR_NVS_BASE + 0x16) /*!< NVS key partition is uninitialized */
#define ESP_ERR_NVS_CORRUPT_KEY_PART (ESP_ERR_NVS_BASE + 0x17) /*!< NVS key partition is corrupt */
#define ESP_ERR_NVS_WRONG_ENCRYPTION (ESP_ERR_NVS_BASE + 0x19) /*!< NVS partition is marked as encrypted with generic flash encryption. This is forbidden since the NVS encryption works differently. */
#define ESP_ERR_NVS_CONTENT_DIFFERS (ESP_ERR_NVS_BASE + 0x18) /*!< Internal error; never returned by nvs API functions. NVS key is different in comparison */
#define NVS_DEFAULT_PART_NAME "nvs" /*!< Default partition name of the NVS partition in the partition table */
#define NVS_PART_NAME_MAX_SIZE 16 /*!< maximum length of partition name (excluding null terminator) */
#define NVS_KEY_NAME_MAX_SIZE 16 /*!< Maximum length of NVS key name (including null terminator) */
#define NVS_NS_NAME_MAX_SIZE NVS_KEY_NAME_MAX_SIZE /*!< Maximum length of NVS namespace name (including null terminator) */
#define NVS_GUARD_SYSVIEW_MACRO_EXPANSION_PUSH() \
_Pragma("push_macro(\"U8\")") \
_Pragma("push_macro(\"I8\")") \
_Pragma("push_macro(\"U16\")") \
_Pragma("push_macro(\"I16\")") \
_Pragma("push_macro(\"U32\")") \
_Pragma("push_macro(\"I32\")") \
_Pragma("push_macro(\"U64\")") \
_Pragma("push_macro(\"I64\")")
#define NVS_GUARD_SYSVIEW_MACRO_EXPANSION_POP() \
_Pragma("pop_macro(\"U8\")") \
_Pragma("pop_macro(\"I8\")") \
_Pragma("pop_macro(\"U16\")") \
_Pragma("pop_macro(\"I16\")") \
_Pragma("pop_macro(\"U32\")") \
_Pragma("pop_macro(\"I32\")") \
_Pragma("pop_macro(\"U64\")") \
_Pragma("pop_macro(\"I64\")")
/**
* @brief Mode of opening the non-volatile storage
*/
typedef enum {
NVS_READONLY, /*!< Read only */
NVS_READWRITE /*!< Read and write */
} nvs_open_mode_t;
/*
* Pre-IDF V4.0 uses nvs_open_mode, so leaving the original typedef here for compatibility.
*/
typedef nvs_open_mode_t nvs_open_mode IDF_DEPRECATED("Replace with nvs_open_mode_t");
/**
* @brief Types of variables
*
*/
typedef enum {
NVS_TYPE_U8 = 0x01, /*!< Type uint8_t */
NVS_TYPE_I8 = 0x11, /*!< Type int8_t */
NVS_TYPE_U16 = 0x02, /*!< Type uint16_t */
NVS_TYPE_I16 = 0x12, /*!< Type int16_t */
NVS_TYPE_U32 = 0x04, /*!< Type uint32_t */
NVS_TYPE_I32 = 0x14, /*!< Type int32_t */
NVS_TYPE_U64 = 0x08, /*!< Type uint64_t */
NVS_TYPE_I64 = 0x18, /*!< Type int64_t */
NVS_TYPE_STR = 0x21, /*!< Type string */
NVS_TYPE_BLOB = 0x42, /*!< Type blob */
NVS_TYPE_ANY = 0xff /*!< Must be last */
} nvs_type_t;
/**
* @brief information about entry obtained from nvs_entry_info function
*/
typedef struct {
char namespace_name[NVS_NS_NAME_MAX_SIZE]; /*!< Namespace to which key-value belong */
char key[NVS_KEY_NAME_MAX_SIZE]; /*!< Key of stored key-value pair */
nvs_type_t type; /*!< Type of stored key-value pair */
} nvs_entry_info_t;
/**
* Opaque pointer type representing iterator to nvs entries
*/
typedef struct nvs_opaque_iterator_t *nvs_iterator_t;
/**
* @brief Open non-volatile storage with a given namespace from the default NVS partition
*
* Multiple internal ESP-IDF and third party application modules can store
* their key-value pairs in the NVS module. In order to reduce possible
* conflicts on key names, each module can use its own namespace.
* The default NVS partition is the one that is labelled "nvs" in the partition
* table.
*
* @param[in] namespace_name Namespace name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[in] open_mode NVS_READWRITE or NVS_READONLY. If NVS_READONLY, will
* open a handle for reading only. All write requests will
* be rejected for this handle.
* @param[out] out_handle If successful (return code is zero), handle will be
* returned in this argument.
*
* @return
* - ESP_OK if storage handle was opened successfully
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - 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_NO_MEM in case 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
* - ESP_ERR_INVALID_ARG if out_handle is equal to NULL
* - other error codes from the underlying storage driver
*/
esp_err_t nvs_open(const char* namespace_name, nvs_open_mode_t open_mode, nvs_handle_t *out_handle);
/**
* @brief Open non-volatile storage with a given namespace from specified partition
*
* The behaviour is same as nvs_open() API. However this API can operate on a specified NVS
* partition instead of default NVS partition. Note that the specified partition must be registered
* with NVS using nvs_flash_init_partition() API.
*
* @param[in] part_name Label (name) of the partition of interest for object read/write/erase
* @param[in] namespace_name Namespace name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[in] open_mode NVS_READWRITE or NVS_READONLY. If NVS_READONLY, will
* open a handle for reading only. All write requests will
* be rejected for this handle.
* @param[out] out_handle If successful (return code is zero), handle will be
* returned in this argument.
*
* @return
* - ESP_OK if storage handle was opened successfully
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized
* - ESP_ERR_NVS_PART_NOT_FOUND if the partition with specified name 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_NO_MEM in case 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
* - ESP_ERR_INVALID_ARG if out_handle is equal to NULL
* - other error codes from the underlying storage driver
*/
esp_err_t nvs_open_from_partition(const char *part_name, const char* namespace_name, nvs_open_mode_t open_mode, nvs_handle_t *out_handle);
/**@{*/
/**
* @brief set int8_t value for given key
*
* Set value for the key, given its name. Note that the actual storage will not be updated
* until \c nvs_commit is called. Regardless whether key-value pair is created or updated,
* function always requires at least one nvs available entry. See \c nvs_get_stats .
* After create type of operation, the number of available entries is decreased by one.
* After update type of operation, the number of available entries remains the same.
*
* @param[in] handle Handle obtained from nvs_open function.
* Handles that were opened read only cannot be used.
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[in] value The value to set.
*
* @return
* - ESP_OK if value was set successfully
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
* - 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_t nvs_set_i8 (nvs_handle_t handle, const char* key, int8_t value);
/**
* @brief set uint8_t value for given key
*
* This function is the same as \c nvs_set_i8 except for the data type.
*/
esp_err_t nvs_set_u8 (nvs_handle_t handle, const char* key, uint8_t value);
/**
* @brief set int16_t value for given key
*
* This function is the same as \c nvs_set_i8 except for the data type.
*/
esp_err_t nvs_set_i16 (nvs_handle_t handle, const char* key, int16_t value);
/**
* @brief set uint16_t value for given key
*
* This function is the same as \c nvs_set_i8 except for the data type.
*/
esp_err_t nvs_set_u16 (nvs_handle_t handle, const char* key, uint16_t value);
/**
* @brief set int32_t value for given key
*
* This function is the same as \c nvs_set_i8 except for the data type.
*/
esp_err_t nvs_set_i32 (nvs_handle_t handle, const char* key, int32_t value);
/**
* @brief set uint32_t value for given key
*
* This function is the same as \c nvs_set_i8 except for the data type.
*/
esp_err_t nvs_set_u32 (nvs_handle_t handle, const char* key, uint32_t value);
/**
* @brief set int64_t value for given key
*
* This function is the same as \c nvs_set_i8 except for the data type.
*/
esp_err_t nvs_set_i64 (nvs_handle_t handle, const char* key, int64_t value);
/**
* @brief set uint64_t value for given key
*
* This function is the same as \c nvs_set_i8 except for the data type.
*/
esp_err_t nvs_set_u64 (nvs_handle_t handle, const char* key, uint64_t value);
/**
* @brief set string for given key
*
* Sets string value for the key. Function requires whole space for new data to be available
* as contiguous entries in same nvs page. Operation consumes 1 overhead entry and 1 entry per
* each 32 characters of new string including zero character to be set. In case of value update
* for existing key, entries occupied by the previous value and overhead entry are returned to
* the pool of available entries.
* Note that storage of long string values can fail due to fragmentation of nvs pages even if
* \c available_entries returned by \c nvs_get_stats suggests enough overall space available.
* Note that the underlying storage will not be updated until \c nvs_commit is called.
*
*
* @param[in] handle Handle obtained from nvs_open function.
* Handles that were opened read only cannot be used.
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[in] value The value to set.
* 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.
*
* @return
* - ESP_OK if value was set successfully
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
* - 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
*/
esp_err_t nvs_set_str (nvs_handle_t handle, const char* key, const char* value);
/**@}*/
/**
* @brief set variable length binary value for given key
*
* Sets variable length binary value for the key. Function uses 2 overhead and 1 entry
* per each 32 bytes of new data from the pool of available entries. See \c nvs_get_stats .
* In case of value update for existing key, space occupied by the existing value and 2 overhead entries
* are returned to the pool of available entries.
* Note that the underlying storage will not be updated until \c nvs_commit is called.
*
* @param[in] handle Handle obtained from nvs_open function.
* Handles that were opened read only cannot be used.
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[in] value The value to set.
* @param[in] length 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_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
* - 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
*/
esp_err_t nvs_set_blob(nvs_handle_t handle, const char* key, const void* value, size_t length);
/**@{*/
/**
* @brief get int8_t value for given key
*
* These functions retrieve value for the key, given its name. If \c 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.
*
* \c out_value has to be a pointer to an already allocated variable of the given type.
*
* \code{c}
* // Example of using nvs_get_i32:
* int32_t max_buffer_size = 4096; // default value
* esp_err_t err = nvs_get_i32(my_handle, "max_buffer_size", &max_buffer_size);
* assert(err == ESP_OK || err == ESP_ERR_NVS_NOT_FOUND);
* // if ESP_ERR_NVS_NOT_FOUND was returned, max_buffer_size will still
* // have its default value.
*
* \endcode
*
* @param[in] handle Handle obtained from nvs_open function.
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param out_value Pointer to the output value.
* May be NULL for nvs_get_str and nvs_get_blob, in this
* case required length will be returned in length argument.
*
* @return
* - ESP_OK if the value was retrieved successfully
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - 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_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data
*/
esp_err_t nvs_get_i8 (nvs_handle_t handle, const char* key, int8_t* out_value);
/**
* @brief get uint8_t value for given key
*
* This function is the same as \c nvs_get_i8 except for the data type.
*/
esp_err_t nvs_get_u8 (nvs_handle_t handle, const char* key, uint8_t* out_value);
/**
* @brief get int16_t value for given key
*
* This function is the same as \c nvs_get_i8 except for the data type.
*/
esp_err_t nvs_get_i16 (nvs_handle_t handle, const char* key, int16_t* out_value);
/**
* @brief get uint16_t value for given key
*
* This function is the same as \c nvs_get_i8 except for the data type.
*/
esp_err_t nvs_get_u16 (nvs_handle_t handle, const char* key, uint16_t* out_value);
/**
* @brief get int32_t value for given key
*
* This function is the same as \c nvs_get_i8 except for the data type.
*/
esp_err_t nvs_get_i32 (nvs_handle_t handle, const char* key, int32_t* out_value);
/**
* @brief get uint32_t value for given key
*
* This function is the same as \c nvs_get_i8 except for the data type.
*/
esp_err_t nvs_get_u32 (nvs_handle_t handle, const char* key, uint32_t* out_value);
/**
* @brief get int64_t value for given key
*
* This function is the same as \c nvs_get_i8 except for the data type.
*/
esp_err_t nvs_get_i64 (nvs_handle_t handle, const char* key, int64_t* out_value);
/**
* @brief get uint64_t value for given key
*
* This function is the same as \c nvs_get_i8 except for the data type.
*/
esp_err_t nvs_get_u64 (nvs_handle_t handle, const char* key, uint64_t* out_value);
/**@}*/
/**@{*/
/**
* @brief get string 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.
*
* All functions expect out_value to be a pointer to an already allocated variable
* of the given type.
*
* nvs_get_str and nvs_get_blob functions support WinAPI-style length queries.
* To get the size necessary to store the value, call nvs_get_str or nvs_get_blob
* with zero out_value and non-zero pointer to length. Variable pointed to
* by length argument will be set to the required length. For nvs_get_str,
* this length includes the zero terminator. When calling nvs_get_str and
* nvs_get_blob with non-zero out_value, length has to be non-zero and has to
* point to the length available in out_value.
* 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.
*
* \code{c}
* // Example (without error checking) of using nvs_get_str to get a string into dynamic array:
* size_t required_size;
* nvs_get_str(my_handle, "server_name", NULL, &required_size);
* char* server_name = malloc(required_size);
* nvs_get_str(my_handle, "server_name", server_name, &required_size);
*
* // Example (without error checking) of using nvs_get_blob to get a binary data
* into a static array:
* uint8_t mac_addr[6];
* size_t size = sizeof(mac_addr);
* nvs_get_blob(my_handle, "dst_mac_addr", mac_addr, &size);
* \endcode
*
* @param[in] handle Handle obtained from nvs_open function.
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[out] out_value Pointer to the output value.
* May be NULL for nvs_get_str and nvs_get_blob, in this
* case required length will be returned in length argument.
* @param[inout] length A non-zero pointer to the variable holding the length of out_value.
* In case out_value a zero, will be set to the length
* required to hold the value. In case out_value is not
* zero, will be set to the actual length of the value
* written. For nvs_get_str this includes zero terminator.
*
* @return
* - ESP_OK if the value was retrieved successfully
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - 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_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_INVALID_LENGTH if \c length is not sufficient to store data
*/
esp_err_t nvs_get_str (nvs_handle_t handle, const char* key, char* out_value, size_t* length);
/**
* @brief get blob value for given key
*
* This function behaves the same as \c nvs_get_str, except for the data type.
*/
esp_err_t nvs_get_blob(nvs_handle_t handle, const char* key, void* out_value, size_t* length);
/**@}*/
/**
* @brief Lookup key-value pair with given key name.
*
* Note that function may indicate both existence of the key as well as the data type of NVS entry if it is found.
*
* @param[in] handle Storage handle obtained with nvs_open.
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[out] out_type Pointer to the output variable populated with data type of NVS entry in case key was found.
* May be NULL, respective data type is then not provided.
* @return
* - ESP_OK if NVS entry for key provided was found
* - 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
*/
esp_err_t nvs_find_key(nvs_handle_t handle, const char* key, nvs_type_t* out_type);
/**
* @brief Erase key-value pair with given key name.
*
* Note that actual storage may not be updated until nvs_commit function is called.
*
* @param[in] handle Storage handle obtained with nvs_open.
* Handles that were opened read only cannot be used.
*
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
*
* @return
* - ESP_OK if erase operation was successful
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
* - ESP_ERR_NVS_READ_ONLY if handle was opened as read only
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
* - other error codes from the underlying storage driver
*/
esp_err_t nvs_erase_key(nvs_handle_t handle, const char* key);
/**
* @brief Erase all key-value pairs in a namespace
*
* Note that actual storage may not be updated until nvs_commit function is called.
*
* @param[in] handle Storage handle obtained with nvs_open.
* Handles that were opened read only cannot be used.
*
* @return
* - ESP_OK if erase operation was successful
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
* - ESP_ERR_NVS_READ_ONLY if handle was opened as read only
* - other error codes from the underlying storage driver
*/
esp_err_t nvs_erase_all(nvs_handle_t handle);
/**
* @brief Write any pending changes to non-volatile storage
*
* After setting any values, nvs_commit() must be called to ensure changes are written
* to non-volatile storage. Individual implementations may write to storage at other times,
* but this is not guaranteed.
*
* @param[in] handle Storage handle obtained with nvs_open.
* Handles that were opened read only cannot be used.
*
* @return
* - ESP_OK if the changes have been written successfully
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
* - other error codes from the underlying storage driver
*/
esp_err_t nvs_commit(nvs_handle_t handle);
/**
* @brief Close the storage handle and free any allocated resources
*
* This function should be called for each handle opened with nvs_open once
* the handle is not in use any more. Closing the handle may not automatically
* write the changes to nonvolatile storage. This has to be done explicitly using
* nvs_commit function.
* Once this function is called on a handle, the handle should no longer be used.
*
* @param[in] handle Storage handle to close
*/
void nvs_close(nvs_handle_t handle);
/**
* @note Info about storage space NVS.
*/
typedef struct {
size_t used_entries; /**< Number of used entries. */
size_t free_entries; /**< Number of free entries. It includes also reserved entries. */
size_t available_entries; /**< Number of entries available for data storage. */
size_t total_entries; /**< Number of all entries. */
size_t namespace_count; /**< Number of namespaces. */
} nvs_stats_t;
/**
* @brief Fill structure nvs_stats_t. It provides info about memory used by NVS.
*
* This function calculates the number of used entries, free entries, available entries, total entries
* and number of namespaces in partition.
*
* \code{c}
* // Example of nvs_get_stats() to get overview of actual statistics of data entries :
* nvs_stats_t nvs_stats;
* nvs_get_stats(NULL, &nvs_stats);
* printf("Count: UsedEntries = (%lu), FreeEntries = (%lu), AvailableEntries = (%lu), AllEntries = (%lu)\n",
nvs_stats.used_entries, nvs_stats.free_entries, nvs_stats.available_entries, nvs_stats.total_entries);
* \endcode
*
* @param[in] part_name Partition name NVS in the partition table.
* If pass a NULL than will use NVS_DEFAULT_PART_NAME ("nvs").
*
* @param[out] nvs_stats Returns filled structure nvs_states_t.
* It provides info about used memory the partition.
*
*
* @return
* - ESP_OK if the changes have been written successfully.
* Return param nvs_stats will be filled.
* - ESP_ERR_NVS_PART_NOT_FOUND if the partition with label "name" is not found.
* Return param nvs_stats will be filled 0.
* - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized.
* Return param nvs_stats will be filled 0.
* - ESP_ERR_INVALID_ARG if nvs_stats is equal to NULL.
* - ESP_ERR_INVALID_STATE if there is page with the status of INVALID.
* Return param nvs_stats will be filled not with correct values because
* not all pages will be counted. Counting will be interrupted at the first INVALID page.
*/
esp_err_t nvs_get_stats(const char *part_name, nvs_stats_t *nvs_stats);
/**
* @brief Calculate all entries in a namespace.
*
* An entry represents the smallest storage unit in NVS.
* Strings and blobs may occupy more than one entry.
* Note that to find out the total number of entries occupied by the namespace,
* add one to the returned value used_entries (if err is equal to ESP_OK).
* Because the name space entry takes one entry.
*
* \code{c}
* // Example of nvs_get_used_entry_count() to get amount of all key-value pairs in one namespace:
* nvs_handle_t handle;
* nvs_open("namespace1", NVS_READWRITE, &handle);
* ...
* size_t used_entries;
* size_t total_entries_namespace;
* if(nvs_get_used_entry_count(handle, &used_entries) == ESP_OK){
* // the total number of entries occupied by the namespace
* total_entries_namespace = used_entries + 1;
* }
* \endcode
*
* @param[in] handle Handle obtained from nvs_open function.
*
* @param[out] used_entries Returns amount of used entries from a namespace.
*
*
* @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_NVS_INVALID_HANDLE if handle has been closed or is NULL.
* Return param used_entries will be filled 0.
* - ESP_ERR_INVALID_ARG if used_entries is equal to NULL.
* - Other error codes from the underlying storage driver.
* Return param used_entries will be filled 0.
*/
esp_err_t nvs_get_used_entry_count(nvs_handle_t handle, size_t* used_entries);
/**
* @brief Create an iterator to enumerate NVS entries based on one or more parameters
*
* \code{c}
* // Example of listing all the key-value pairs of any type under specified partition and namespace
* nvs_iterator_t it = NULL;
* 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);
* }
* nvs_release_iterator(it);
* \endcode
*
* @param[in] part_name Partition name
*
* @param[in] namespace_name Set this value if looking for entries with
* a specific namespace. Pass NULL otherwise.
*
* @param[in] type One of nvs_type_t values.
*
* @param[out] output_iterator
* Set to a valid iterator to enumerate all the entries found.
* Set to NULL if no entry for specified criteria was found.
* If any other error except ESP_ERR_INVALID_ARG occurs, \c output_iterator is NULL, too.
* If ESP_ERR_INVALID_ARG occurs, \c output_iterator is not changed.
* If a valid iterator is obtained through this function, it has to be released
* using \c nvs_release_iterator when not used any more, unless ESP_ERR_INVALID_ARG is returned.
*
* @return
* - ESP_OK if no internal error or programming error occurred.
* - ESP_ERR_NVS_NOT_FOUND if no element of specified criteria has been found.
* - ESP_ERR_NO_MEM if memory has been exhausted during allocation of internal structures.
* - ESP_ERR_INVALID_ARG if any of the parameters is NULL.
* Note: don't release \c output_iterator in case ESP_ERR_INVALID_ARG has been returned
*/
esp_err_t nvs_entry_find(const char *part_name,
const char *namespace_name,
nvs_type_t type,
nvs_iterator_t *output_iterator);
/**
* @brief Create an iterator to enumerate NVS entries based on a handle and type
*
* \code{c}
* // Example of listing all the key-value pairs of any type under specified handle (which defines a partition and namespace)
* nvs_iterator_t it = NULL;
* esp_err_t res = nvs_entry_find_in_handle(<nvs_handle>, 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);
* }
* nvs_release_iterator(it);
* \endcode
*
* @param[in] handle Handle obtained from nvs_open function.
*
* @param[in] type One of nvs_type_t values.
*
* @param[out] output_iterator
* Set to a valid iterator to enumerate all the entries found.
* Set to NULL if no entry for specified criteria was found.
* If any other error except ESP_ERR_INVALID_ARG occurs, \c output_iterator is NULL, too.
* If ESP_ERR_INVALID_ARG occurs, \c output_iterator is not changed.
* If a valid iterator is obtained through this function, it has to be released
* using \c nvs_release_iterator when not used any more, unless ESP_ERR_INVALID_ARG is returned.
*
* @return
* - ESP_OK if no internal error or programming error occurred.
* - ESP_ERR_NVS_NOT_FOUND if no element of specified criteria has been found.
* - ESP_ERR_NO_MEM if memory has been exhausted during allocation of internal structures.
* - ESP_ERR_NVS_INVALID_HANDLE if unknown handle was specified.
* - ESP_ERR_INVALID_ARG if output_iterator parameter is NULL.
* Note: don't release \c output_iterator in case ESP_ERR_INVALID_ARG has been returned
*/
esp_err_t nvs_entry_find_in_handle(nvs_handle_t handle, nvs_type_t type, nvs_iterator_t *output_iterator);
/**
* @brief Advances the iterator to next item matching the iterator criteria.
*
* Note that any copies of the iterator will be invalid after this call.
*
* @param[inout] iterator Iterator obtained from nvs_entry_find or nvs_entry_find_in_handle
* function. Must be non-NULL. If any error except ESP_ERR_INVALID_ARG
* occurs, \c iterator is set to NULL. If ESP_ERR_INVALID_ARG occurs, \c
* iterator is not changed.
*
* @return
* - ESP_OK if no internal error or programming error occurred.
* - ESP_ERR_NVS_NOT_FOUND if no next element matching the iterator criteria.
* - ESP_ERR_INVALID_ARG if \c iterator is NULL.
* - Possibly other errors in the future for internal programming or flash errors.
*/
esp_err_t nvs_entry_next(nvs_iterator_t *iterator);
/**
* @brief Fills nvs_entry_info_t structure with information about entry pointed to by the iterator.
*
* @param[in] iterator Iterator obtained from nvs_entry_find or nvs_entry_find_in_handle
* function. Must be non-NULL.
*
* @param[out] out_info Structure to which entry information is copied.
*
* @return
* - ESP_OK if all parameters are valid; current iterator data has been written to out_info
* - ESP_ERR_INVALID_ARG if one of the parameters is NULL.
*/
esp_err_t nvs_entry_info(const nvs_iterator_t iterator, nvs_entry_info_t *out_info);
/**
* @brief Release iterator
*
* @param[in] iterator Release iterator obtained from nvs_entry_find or
* nvs_entry_find_in_handle or nvs_entry_next function. NULL argument is
* allowed.
*
*/
void nvs_release_iterator(nvs_iterator_t iterator);
#ifdef __cplusplus
} // extern "C"
#endif
#endif //ESP_NVS_H
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.