Line data    Source code

       1             : /*
       2             :  *
       3             :  *    Copyright (c) 2020-2022 Project CHIP Authors
       4             :  *    All rights reserved.
       5             :  *
       6             :  *    Licensed under the Apache License, Version 2.0 (the "License");
       7             :  *    you may not use this file except in compliance with the License.
       8             :  *    You may obtain a copy of the License at
       9             :  *
      10             :  *        http://www.apache.org/licenses/LICENSE-2.0
      11             :  *
      12             :  *    Unless required by applicable law or agreed to in writing, software
      13             :  *    distributed under the License is distributed on an "AS IS" BASIS,
      14             :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      15             :  *    See the License for the specific language governing permissions and
      16             :  *    limitations under the License.
      17             :  */
      18             : 
      19             : #pragma once
      20             : 
      21             : #include <lib/core/CHIPError.h>
      22             : #include <lib/support/DLLUtil.h>
      23             : #include <stddef.h>
      24             : #include <stdint.h>
      25             : 
      26             : namespace chip {
      27             : 
      28             : class DLL_EXPORT PersistentStorageDelegate
      29             : {
      30             : public:
      31             :     /**
      32             :      *  Maximum length of a key required by implementations. Any implementer of PersistentStorageDelegate
      33             :      *  must support keys AT LEAST this long.
      34             :      */
      35             :     static constexpr size_t kKeyLengthMax = 32;
      36             : 
      37           0 :     virtual ~PersistentStorageDelegate() {}
      38             : 
      39             :     /**
      40             :      * @brief
      41             :      *   This is a synchronous Get API, where the value is returned via the output
      42             :      *   buffer.
      43             :      *
      44             :      *   This API can be used to retrieve a byte buffer value from the storage.
      45             :      *   There is no implied data format and and data will be stored/fetched binary.
      46             :      *   Caller is responsible to take care of any special formatting needs (e.g. byte
      47             :      *   order, null terminators, consistency checks or versioning).
      48             :      *
      49             :      *   If a key is found and the `buffer`'s `size` is large enough, then the value will
      50             :      *   be copied to `buffer` and `size` will be updated to the actual size used.
      51             :      *
      52             :      *   Whenever the passed `size` is smaller than the size of the stored value for the given key,
      53             :      *   CHIP_ERROR_BUFFER_TOO_SMALL will be returned, but the `buffer` will still be filled with the
      54             :      *   first `size` bytes of the stored value.
      55             :      *
      56             :      *   In the case where `size` of 0 is given, and the value stored is of size 0, CHIP_NO_ERROR is
      57             :      *   returned. It is recommended to use helper method SyncDoesKeyExist(key) to determine if key
      58             :      *   exists.
      59             :      *
      60             :      *   It is legal to use `nullptr` for `buffer` if `size` is 0.
      61             :      *
      62             :      * @param[in]      key Key to lookup
      63             :      * @param[out]     buffer Pointer to a buffer where the place the read value.
      64             :      * @param[in, out] size Input is maximum buffer size, output updated to number of bytes written into `buffer`.
      65             :      *
      66             :      * @return CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND the key is not found in storage.
      67             :      * @return CHIP_ERROR_BUFFER_TOO_SMALL the provided buffer is not big enough.  In this case
      68             :      *                                     the first `size` bytes of the value will be placed in `buffer`.
      69             :      */
      70             :     virtual CHIP_ERROR SyncGetKeyValue(const char * key, void * buffer, uint16_t & size) = 0;
      71             : 
      72             :     /**
      73             :      * @brief
      74             :      *   Set the value for the key to a byte buffer. Empty values can be stored
      75             :      *   with size == 0, in which case `value` may be nullptr.
      76             :      *
      77             :      * @param[in] key Key to set
      78             :      * @param[in] value Pointer to bytes of value to be set. `value` can only be `nullptr` if size == 0.
      79             :      * @param[in] size Size of the `value` to store.
      80             :      *
      81             :      * @return CHIP_NO_ERROR on success, CHIP_INVALID_ARGUMENT on `value` being `nullptr` with size > 0,
      82             :      *         or another CHIP_ERROR value from implementation on failure.
      83             :      */
      84             :     virtual CHIP_ERROR SyncSetKeyValue(const char * key, const void * value, uint16_t size) = 0;
      85             : 
      86             :     /**
      87             :      * @brief
      88             :      *   Deletes the value for the key
      89             :      *
      90             :      * @param[in] key Key to be deleted
      91             :      *
      92             :      * @return CHIP_NO_ERROR on success, CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND if the key is not found in storage,
      93             :      *         or another CHIP_ERROR value from implementation on failure.
      94             :      */
      95             :     virtual CHIP_ERROR SyncDeleteKeyValue(const char * key) = 0;
      96             : 
      97             :     /**
      98             :      * @brief
      99             :      *   Helper function that identifies if a key exists.
     100             :      *
     101             :      *   This may be overridden to provide an implementation that is simpler or more direct.
     102             :      *
     103             :      * @param[in] key Key to check if it exist
     104             :      *
     105             :      * @return true if key exists in storage. It returns false if key does not exist in storage or an internal error arises.
     106             :      */
     107           0 :     virtual bool SyncDoesKeyExist(const char * key)
     108             :     {
     109           0 :         uint16_t size  = 0;
     110           0 :         CHIP_ERROR err = SyncGetKeyValue(key, nullptr, size);
     111           0 :         return (err == CHIP_ERROR_BUFFER_TOO_SMALL) || (err == CHIP_NO_ERROR);
     112             :     }
     113             : };
     114             : 
     115             : } // namespace chip