arduino-esp32-custom-lwip-ppp-enabled/docs/source/api/preferences.rst

###########
Preferences
###########

About
-----

The Preferences library is unique to arduino-esp32. It should be considered as the replacement for the Arduino EEPROM library.

It uses a portion of the on-board non-volatile memory (NVS) of the ESP32 to store data. This data is retained across restarts and loss of power events to the system. 

Preferences works best for storing many small values, rather than a few large values. If large amounts of data are to be stored, consider using a file system library such as LitteFS.

The Preferences library is usable by all ESP32 variants.


Header File
-----------

.. code-block:: arduino

    #include <Preferences.h>
..


Overview
--------

Library methods are provided to:
   - create a namespace;
   - open and close a namespace;
   - store and retrieve data within a namespace for supported data types;
   - determine if a key value has been initialized;
   - delete a ``key-value`` pair;
   - delete all ``key-value`` pairs in a namespace;
   - determine data types stored against a key;
   - determine the number of key entries in the namespace.

Preferences directly supports the following data types:

.. table:: **Table 1 — Preferences Data Types**
   :align: center
   
   +-------------------+-------------------+---------------+
   | Preferences Type  | Data Type         | Size (bytes)  |
   +===================+===================+===============+
   | Bool              | bool              | 1             |
   +-------------------+-------------------+---------------+
   | Char              | int8_t            | 1             |
   +-------------------+-------------------+---------------+
   | UChar             | uint8_t           | 1             |
   +-------------------+-------------------+---------------+
   | Short             | int16_t           | 2             |
   +-------------------+-------------------+---------------+
   | UShort            | uint16_t          | 2             |
   +-------------------+-------------------+---------------+
   | Int               | int32_t           | 4             |
   +-------------------+-------------------+---------------+
   | UInt              | uint32_t          | 4             |
   +-------------------+-------------------+---------------+
   | Long              | int32_t           | 4             |
   +-------------------+-------------------+---------------+
   | ULong             | uint32_t          | 4             |
   +-------------------+-------------------+---------------+
   | Long64            | int64_t           | 8             |
   +-------------------+-------------------+---------------+
   | ULong64           | uint64_t          | 8             |
   +-------------------+-------------------+---------------+
   | Float             | float_t           | 8             |
   +-------------------+-------------------+---------------+
   | Double            | double_t          | 8             |
   +-------------------+-------------------+---------------+
   |                   | const char*       | variable      |
   | String            +-------------------+               |
   |                   | String            |               |
   +-------------------+-------------------+---------------+
   | Bytes             | uint8_t           | variable      |
   +-------------------+-------------------+---------------+

String values can be stored and retrieved either as an Arduino String or as a null terminated ``char`` array (c-string).

Bytes type is used for storing and retrieving an arbitrary number of bytes in a namespace.


Arduino-esp32 Preferences API
-----------------------------

``begin``
**********

   Open non-volatile storage with a given namespace name from an NVS partition.

   .. code-block:: arduino

     bool begin(const char * name, bool readOnly=false, const char* partition_label=NULL)
   ..

   **Parameters**
      * ``name`` (Required)
         - Namespace name. Maximum length is 15 characters.

      * ``readOnly`` (Optional)
         - ``false`` will open the namespace in read-write mode.
         - ``true``  will open the namespace in read-only mode.
         - if omitted, the namespace is opened in read-write mode.

      * ``partition_label`` (Optional)
         - name of the NVS partition in which to open the namespace.
         - if omitted, the namespace is opened in the "``nvs``" partition.

   **Returns**
      * ``true`` if the namespace was opened successfully; ``false`` otherwise.

   **Notes**
      * If the namespace does not exist within the partition, it is first created.
      * Attempting to write a key value to a namespace open in read-only mode will fail. 
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.


``end``
*********

   Close the currently opened namespace.

   .. code-block:: arduino
                       
      void end()          
   ..

   **Parameters**
      * None

   **Returns**
      * Nothing

   **Note**
      * After closing a namespace, methods used to access it will fail. 


``clear``
**********

   Delete all keys and values from the currently opened namespace.

   .. code-block:: arduino 
                        
      bool clear()         
   ..

   **Parameters**
      * None
   
   **Returns**
      * ``true`` if all keys and values were deleted; ``false`` otherwise.
   
   **Note**
      * the namespace name still exists afterward. 
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
  
  
``remove``
*************

   Delete a key-value pair from the currently open namespace.
   
   .. code-block:: arduino
   
       bool remove(const char * key)
   ..

   **Parameters**
      * ``key`` (Required)
         -  the name of the key to be deleted. 
   
   **Returns**
      * ``true`` if key-value pair was deleted; ``false`` otherwise.
   
   **Note** 
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.


``putChar, putUChar``
**********************

   Store a value against a given key in the currently open namespace.

   .. code-block:: arduino

       size_t putChar(const char* key, int8_t value)
       size_t putUChar(const char* key, uint8_t value)

   ..

   **Parameters**
      * ``key`` (Required)
         - if the key does not exist in the currently opened namespace it is first created.

      * ``value`` (Required)
         - must match the data type of the method.
         
   **Returns**
      * ``1`` (the number of bytes stored for these data types) if the call is successful; ``0`` otherwise.

   **Notes**
      * Attempting to store a value without a namespace being open in read-write mode will fail.
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.


``putShort, putUShort``
************************

   Store a value against a given key in the currently open namespace.

   .. code-block:: arduino

       size_t putShort(const char* key, int16_t value)
       size_t putUShort(const char* key, uint16_t value)

   ..

   **Parameters**
      * ``key`` (Required)
         - if the key does not exist in the currently opened namespace it is first created.

      * ``value`` (Required)
         - must match the data type of the method.
         
   **Returns**
      * ``2`` (the number of bytes stored for these data types) if the call is successful; ``0`` otherwise.

   **Notes**
      * Attempting to store a value without a namespace being open in read-write mode will fail.
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.



``putInt, putUInt``
********************
``putLong, putULong``
**********************

   Store a value against a given key in the currently open namespace.
   
   .. code-block:: arduino

       size_t putInt(const char* key, int32_t value)
       size_t putUInt(const char* key, uint32_t value)
       size_t putLong(const char* key, int32_t value)
       size_t putULong(const char* key, uint32_t value)

   ..

   **Parameters**
      * ``key`` (Required)
         - if the key does not exist in the currently opened namespace it is first created.

      * ``value`` (Required)
         - must match the data type of the method.
         
   **Returns**
      * ``4`` (the number of bytes stored for these data types) if the call is successful; ``0`` otherwise.

   **Notes**
      * Attempting to store a value without a namespace being open in read-write mode will fail.
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.


``putLong64, putULong64``
*************************
``putFloat, putDouble``
***********************

   Store a value against a given key in the currently open namespace.

   .. code-block:: arduino

       size_t putLong64(const char* key, int64_t value)
       size_t putULong64(const char* key, uint64_t value)
       size_t putFloat(const char* key, float_t value)
       size_t putDouble(const char* key, double_t value)

   ..

   **Parameters**
      * ``key`` (Required)
         - if the key does not exist in the currently opened namespace it is first created.

      * ``value`` (Required)
         - must match the data type of the method.
         
   **Returns**
      * ``8`` (the number of bytes stored for these data types) if the call is successful; ``0`` otherwise.

   **Notes**
      * Attempting to store a value without a namespace being open in read-write mode will fail.
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.


``putBool``
***********

   Store a value against a given key in the currently open namespace.

   .. code-block:: arduino

          size_t putBool(const char* key, bool value)

   ..

   **Parameters**
      * ``key`` (Required)
         - if the key does not exist in the currently opened namespace it is first created.

      * ``value`` (Required)
         - must match the data type of the method.
         
   **Returns**
      * ``true`` if successful; ``false`` otherwise.

   **Notes**
      * Attempting to store a value without a namespace being open in read-write mode will fail.
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.


``putString``
**************

   Store a variable length value against a given key in the currently open namespace.

   .. code-block:: arduino

       size_t putString(const char* key, const char* value);
       size_t putString(const char* key, String value);

   ..

   **Parameters**
      * ``key`` (Required)
         - if the key does not exist in the currently opened namespace it is first created.

      * ``value`` (Required)
         - if ``const char*``, a null-terminated (c-string) character array.         
         - if ``String``, a valid Arduino String type.
         
   **Returns**
      * if successful: the number of bytes stored; ``0`` otherwise.

   **Notes**
      * Attempting to store a value without a namespace being open in read-write mode will fail.
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.


``putBytes``
************

   Store a variable number of bytes against a given key in the currently open namespace.

   .. code-block:: arduino

       size_t putBytes(const char* key, const void* value, size_t len);

   ..

   **Parameters**
      * ``key`` (Required)
         - if the key does not exist in the currently opened namespace it is first created.

      * ``value`` (Required)
         - pointer to an array or buffer containing the bytes to be stored.

      * ``len`` (Required)
         - the number of bytes from ``value`` to be stored.
         
   **Returns**
      *  if successful: the number of bytes stored; ``0`` otherwise.

   **Notes**
      * Attempting to store a value without a namespace being open in read-write mode will fail.
      * This method operates on the bytes used by the underlying data type, not the number of elements of a given data type. The data type of ``value`` is not retained by the Preferences library afterward. 
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.


``getChar, getUChar``
*********************

   Retrieve a value stored against a given key in the currently open namespace.

   .. code-block:: arduino

      int8_t getChar(const char* key, int8_t defaultValue = 0)
      uint8_t getUChar(const char* key, uint8_t defaultValue = 0)

   ..

   **Parameters**
      * ``key`` (Required)

      * ``defaultValue`` (Optional)
         - must match the data type of the method if provided.
         
   **Returns**
      * the value stored against ``key`` if the call is successful.
      * ``defaultValue``, if it is provided; ``0`` otherwise.

   **Notes**
      * Attempting to retrieve a key without a namespace being available will fail.
      * Attempting to retrieve value from a non existant key will fail.
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.


``getShort, getUShort``
****************************

   Retrieve a value stored against a given key in the currently open namespace.

   .. code-block:: arduino

      int16_t getShort(const char* key, int16_t defaultValue = 0)
      uint16_t getUShort(const char* key, uint16_t defaultValue = 0)
   ..
   
   Except for the data type returned, behaves exactly like ``getChar``.



``getInt, getUInt``
*******************

   Retrieve a value stored against a given key in the currently open namespace.

   .. code-block:: arduino

    int32_t getInt(const char* key, int32_t defaultValue = 0)
    uint32_t getUInt(const char* key, uint32_t defaultValue = 0)

   ..
   
   Except for the data type returned, behaves exactly like ``getChar``.


``getLong, getULong``
*********************

   Retrieve a value stored against a given key in the currently open namespace.

   .. code-block:: arduino

      int32_t getLong(const char* key, int32_t defaultValue = 0)
      uint32_t getULong(const char* key, uint32_t defaultValue = 0)

   ..
   
   Except for the data type returned, behaves exactly like ``getChar``.


``getLong64, getULong64``
*************************

   Retrieve a value stored against a given key in the currently open namespace.

   .. code-block:: arduino

      int64_t getLong64(const char* key, int64_t defaultValue = 0)
      uint64_t getULong64(const char* key, uint64_t defaultValue = 0)

   ..
   
   Except for the data type returned, behaves exactly like ``getChar``.


``getFloat``
*************

   Retrieve a value stored against a given key in the currently open namespace.

   .. code-block:: arduino

      float_t getFloat(const char* key, float_t defaultValue = NAN)

   ..
   
   Except for the data type returned and the value of ``defaultValue``, behaves exactly like ``getChar``.


``getDouble``
*************

   Retrieve a value stored against a given key in the currently open namespace.

   .. code-block:: arduino

      double_t getDouble(const char* key, double_t defaultValue = NAN)

   ..
   
   Except for the data type returned and the value of ``defaultValue``, behaves exactly like ``getChar``.


``getBool``
************

   Retrieve a value stored against a given key in the currently open namespace.

   .. code-block:: arduino

      uint8_t getUChar(const char* key, uint8_t defaultValue = 0);

   ..
   
   Except for the data type returned, behaves exactly like ``getChar``.


``getString``
*************

   Copy a string of ``char`` stored against a given key in the currently open namespace to a buffer.

.. code-block:: arduino

    size_t getString(const char* key, char* value, size_t len);
..

   **Parameters**
      * ``key`` (Required)
      * ``value`` (Required)
         - a buffer of a size large enough to hold ``len`` bytes
      * ``len`` (Required)
         - the number of type ``char``` to be written to the buffer pointed to by ``value``

   **Returns**
      * if successful; the number of bytes equal to ``len`` is written to the buffer pointed to by ``value``, and the method returns ``1``.
      * if the method fails, nothing is written to the buffer pointed to by ``value`` and the method returns ``0``.

   **Notes**
      * ``len`` must equal the number of bytes stored against the key or the call will fail.
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.


``getString``
*************

   Retrieve an Arduino String value stored against a given key in the currently open namespace.

.. code-block:: arduino

    String getString(const char* key, String defaultValue = String());

..

   **Parameters**
      * ``key`` (Required)
      * ``defaultValue`` (Optional)
         
   **Returns**
      * the value stored against ``key`` if the call if successful
      * if the method fails: it returns ``defaultValue``, if provided; ``""`` (an empty String) otherwise.

   **Notes**
      * ``defaultValue`` must be of type ``String``.


``getBytes``
*************

Copy a series of bytes stored against a given key in the currently open namespace to a buffer.

.. code-block:: arduino

   size_t getBytes(const char* key, void * buf, size_t len);

..

   **Parameters**
      * ``key`` (Required)
      * ``buf`` (Required)
         - a buffer of a size large enough to hold ``len`` bytes.
      * ``len`` (Required)
         - the number of bytes to be written to the buffer pointed to by ``buf``

   **Returns**
      * if successful, the number of bytes equal to ``len`` is written to buffer ``buf``, and the method returns ``1``.
      * if the method fails, nothing is written to the buffer and the method returns ``0``.

   **Notes**
      * ``len`` must equal the number of bytes stored against the key or the call will fail.
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.


``getBytesLength``
******************

Get the number of bytes stored in the value against a key of type ``Bytes`` in the currently open namespace.

.. code-block:: arduino

   size_t getBytesLength(const char* key)

..

   **Parameters**
      * ``key`` (Required)

   **Returns**
      * if successful: the number of bytes in the value stored against ``key``; ``0`` otherwise.
      
   **Notes**
      * This method will fail if ``key`` is not of type ``Bytes``.
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.


``getType``
***********

Get the Preferences data type of a given key within the currently open namespace.

.. code-block:: arduino

   PreferenceType getType(const char* key)

..

   **Parameters**
      * ``key`` (Required)

   **Returns**
      * an ``int`` value as per Table 2 below.
      * a value of ``10`` (PT_INVALID) if the call fails.
      
   **Notes**
      * The return values are enumerated in ``Preferences.h``. Table 2 includes the enumerated values for information.
      * A return value can map to more than one Prefs Type.
      * The method will fail if: the namespace is not open; the key does not exist; the provided key exceeds 15 characters.

.. table:: **Table 2 — getType Return Values**
   :align: center
   
   +---------------+---------------+-------------------+-----------------------+
   | Return value  | Prefs Type    | Data Type         | Enumerated Value      |
   +===============+===============+===================+=======================+
   | 0             | Char          | int8_t            | PT_I8                 |
   +---------------+---------------+-------------------+-----------------------+
   | 1             | UChar         | uint8_t           | PT_U8                 |
   |               +---------------+-------------------+                       |
   |               | Bool          | bool              |                       |
   +---------------+---------------+-------------------+-----------------------+
   | 2             | Short         | int16_t           | PT_I16                |
   +---------------+---------------+-------------------+-----------------------+
   | 3             | UShort        | uint16_t          | PT_U16                |
   +---------------+---------------+-------------------+-----------------------+
   | 4             | Int           | int32_t           | PT_I32                |
   |               +---------------+                   |                       |
   |               | Long          |                   |                       |
   +---------------+---------------+-------------------+-----------------------+
   | 5             | UInt          | uint32_t          | PT_U32                |
   |               +---------------+                   |                       |
   |               | ULong         |                   |                       |
   +---------------+---------------+-------------------+-----------------------+
   | 6             | Long64        | int64_t           | PT_I64                |
   +---------------+---------------+-------------------+-----------------------+
   | 7             | ULong64       | uint64_t          | PT_U64                |
   +---------------+---------------+-------------------+-----------------------+
   | 8             | String        | String            | PT_STR                |
   |               |               +-------------------+                       |
   |               |               | \*char            |                       |
   +---------------+---------------+-------------------+-----------------------+
   | 9             | Double        | double_t          | PT_BLOB               |
   |               +---------------+-------------------+                       |
   |               | Float         | float_t           |                       |
   |               +---------------+-------------------+                       |   
   |               | Bytes         | uint8_t           |                       |
   +---------------+---------------+-------------------+-----------------------+
   | 10            | \-            | \-                | PT_INVALID            |
   +---------------+---------------+-------------------+-----------------------+


``freeEntries``
***************

Get the number of free entries available in the key table of the currently open namespace.

.. code-block:: arduino

   size_t freeEntries()

..

   **Parameters**
      * none

   **Returns**
      * if successful: the number of free entries available in the key table of the currently open namespace; ``0`` otherwise.
      
   **Notes**
      * keys storing values of type ``Bool``, ``Char``, ``UChar``, ``Short``, ``UShort``, ``Int``, ``UInt``, ``Long``, ``ULong``, ``Long64``, ``ULong64`` use one entry in the key table.
      * keys storing values of type ``Float`` and ``Double`` use three entries in the key table.
      * Arduino or c-string ``String`` types use a minimum of two key table entries with the number of entries increasing with the length of the string. 
      * keys storing values of type ``Bytes`` use a minimum of three key table entries with the number of entries increasing with the number of bytes stored. 
      * A message providing the reason for a failed call is sent to the arduino-esp32 ``log_e`` facility.
      

..    --- EOF ----