Line data    Source code

       1             : /*
       2             :  *
       3             :  *    Copyright (c) 2021 Project CHIP Authors
       4             :  *
       5             :  *    Licensed under the Apache License, Version 2.0 (the "License");
       6             :  *    you may not use this file except in compliance with the License.
       7             :  *    You may obtain a copy of the License at
       8             :  *
       9             :  *        http://www.apache.org/licenses/LICENSE-2.0
      10             :  *
      11             :  *    Unless required by applicable law or agreed to in writing, software
      12             :  *    distributed under the License is distributed on an "AS IS" BASIS,
      13             :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      14             :  *    See the License for the specific language governing permissions and
      15             :  *    limitations under the License.
      16             :  */
      17             : 
      18             : /**
      19             :  * @file
      20             :  *
      21             :  * @brief
      22             :  *   API function declarations for using persistent key value storage.
      23             :  */
      24             : 
      25             : #pragma once
      26             : 
      27             : #include <climits>
      28             : #include <cstddef>
      29             : #include <cstdint>
      30             : #include <type_traits>
      31             : 
      32             : #include <lib/core/CHIPError.h>
      33             : #include <platform/CHIPDeviceConfig.h>
      34             : 
      35             : namespace chip {
      36             : namespace DeviceLayer {
      37             : namespace PersistedStorage {
      38             : class KeyValueStoreManagerImpl;
      39             : 
      40             : class KeyValueStoreManager
      41             : {
      42             : public:
      43             :     /**
      44             :      * @brief
      45             :      *   Reads the value of an entry in the KVS. The value is read into the
      46             :      *   provided buffer and the number of bytes read is returned. If desired,
      47             :      *   the read can be started at an offset.
      48             :      *
      49             :      *   If the output buffer is too small for the value, Get returns
      50             :      *   CHIP_ERROR_BUFFER_TOO_SMALL with the number of bytes read returned in
      51             :      *   read_bytes_size, which should be the buffer_size.
      52             :      *
      53             :      *   The remainder of the  value can be read by calling get with an offset.
      54             :      *
      55             :      * @param[in]     key               The name of the key to get, this is a
      56             :      *                                  null-terminated string.
      57             :      * @param[in,out] buffer            A buffer to read the value into.
      58             :      * @param[in]     buffer_size       The size of the buffer in bytes.
      59             :      * @param[in]     read_bytes_size   The number of bytes which were
      60             :      *                                  copied into the buffer. Optionally can
      61             :      *                                  provide nullptr if not needed.
      62             :      * @param[in]     offset_bytes      The offset byte index to start the read.
      63             :      *
      64             :      * @return CHIP_NO_ERROR the entry was successfully read
      65             :      *         CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND the key is not
      66             :      *                                                       present in the KVS
      67             :      *         CHIP_ERROR_INTEGRITY_CHECK_FAILED found the entry, but the data
      68             :      *                                           was corrupted
      69             :      *         CHIP_ERROR_BUFFER_TOO_SMALL the buffer could not fit the entire
      70             :      *                                     value, but as many bytes as possible
      71             :      *                                     were written to it
      72             :      *         CHIP_ERROR_UNINITIALIZED the KVS is not initialized
      73             :      *         CHIP_ERROR_INVALID_ARGUMENT key is empty or too long or value is
      74             :      *                                     too large
      75             :      */
      76             :     CHIP_ERROR Get(const char * key, void * buffer, size_t buffer_size, size_t * read_bytes_size = nullptr,
      77             :                    size_t offset_bytes = 0);
      78             : 
      79             :     /**
      80             :      * @brief
      81             :      * This overload of Get accepts a pointer to a trivially copyable object.
      82             :      * The size of the object is inferred from the type.
      83             :      *
      84             :      * @param[in]      key     The name of the key in to get, this is a
      85             :      *                         null-terminated string.
      86             :      * @param[in,out]  value   Pointer to a trivially copyable object.
      87             :      *
      88             :      * @return CHIP_NO_ERROR the entry was successfully read
      89             :      *         CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND the key is not
      90             :      *                                                      present in the KVS
      91             :      *         CHIP_ERROR_INTEGRITY_CHECK_FAILED found the entry, but the data
      92             :      *                                           was corrupted
      93             :      *         CHIP_ERROR_BUFFER_TOO_SMALL the buffer could not fit the entire
      94             :      *                                     value, but as many bytes as possible
      95             :      *                                     were written to it
      96             :      *         CHIP_ERROR_UNINITIALIZED the KVS is not initialized
      97             :      *         CHIP_ERROR_INVALID_ARGUMENT key is empty or too long or value is
      98             :      *                                     too large
      99             :      */
     100             :     template <typename T>
     101             :     CHIP_ERROR Get(const char * key, T * value)
     102             :     {
     103             :         static_assert(std::is_trivially_copyable<T>(), "KVS values must copyable");
     104             :         static_assert(!std::is_pointer<T>(), "KVS values cannot be pointers");
     105             :         static_assert(CHAR_BIT == 8, "Current implementation assumes 8 bit.");
     106             :         return Get(key, value, sizeof(T));
     107             :     }
     108             : 
     109             :     /**
     110             :      * @brief
     111             :      * Adds a key-value entry to the KVS. If the key was already present, its
     112             :      * value is overwritten.
     113             :      *
     114             :      * @param[in]  key          The name of the key to update, this is a
     115             :      *                          null-terminated string.
     116             :      * @param[in]  value        Pointer to the data.
     117             :      * @param[in]  value_size   Size of the data.
     118             :      *
     119             :      * @return CHIP_NO_ERROR the entry was successfully added or updated
     120             :      *         CHIP_ERROR_INTEGRITY_CHECK_FAILED checksum validation failed after
     121             :      *                                           writing the data
     122             :      *         CHIP_ERROR_PERSISTED_STORAGE_FAILED failed to write the value.
     123             :      *         CHIP_ERROR_UNINITIALIZED the KVS is not initialized
     124             :      *         CHIP_ERROR_INVALID_ARGUMENT key is empty or too long or value is
     125             :      *                                     too large
     126             :      */
     127             :     CHIP_ERROR Put(const char * key, const void * value, size_t value_size);
     128             : 
     129             :     /**
     130             :      * @brief
     131             :      * This overload of Put accepts a reference to a trivially copyable object.
     132             :      * The size of the object is inferred from the type.
     133             :      *
     134             :      * @param[in]  key     The name of the key to update, this is a
     135             :      *                     null-terminated string.
     136             :      * @param[in]  value   Reference of a trivially copyable object.
     137             :      *
     138             :      * @return CHIP_NO_ERROR the entry was successfully added or updated
     139             :      *         CHIP_ERROR_INTEGRITY_CHECK_FAILED checksum validation failed after
     140             :      *                                           writing the data
     141             :      *         CHIP_ERROR_PERSISTED_STORAGE_FAILED failed to write the value.
     142             :      *         CHIP_ERROR_UNINITIALIZED the KVS is not initialized
     143             :      *         CHIP_ERROR_INVALID_ARGUMENT key is empty or too long or value is
     144             :      *                                     too large
     145             :      */
     146             :     template <typename T>
     147             :     CHIP_ERROR Put(const char * key, const T & value)
     148             :     {
     149             :         static_assert(std::is_trivially_copyable<T>(), "KVS values must copyable");
     150             :         static_assert(!std::is_pointer<T>(), "KVS values cannot be pointers");
     151             :         static_assert(CHAR_BIT == 8, "Current implementation assumes 8 bit.");
     152             :         return Put(key, &value, sizeof(T));
     153             :     }
     154             : 
     155             :     /**
     156             :      * @brief
     157             :      * Removes a key-value entry from the KVS.
     158             :      *
     159             :      * @param[in]      key       The name of the key to delete, this is a
     160             :      *                           null-terminated string.
     161             :      *
     162             :      * @return CHIP_NO_ERROR the entry was successfully deleted.
     163             :      *         CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND the key is not
     164             :      *                                                      present in the KVS
     165             :      *         CHIP_ERROR_INTEGRITY_CHECK_FAILED checksum validation failed after
     166             :      *                                           erasing data
     167             :      *         CHIP_ERROR_PERSISTED_STORAGE_FAILED failed to erase the value.
     168             :      *         CHIP_ERROR_UNINITIALIZED the KVS is not initialized
     169             :      *         CHIP_ERROR_INVALID_ARGUMENT key is empty or too long
     170             :      */
     171             :     CHIP_ERROR Delete(const char * key);
     172             : 
     173             : private:
     174             :     using ImplClass = ::chip::DeviceLayer::PersistedStorage::KeyValueStoreManagerImpl;
     175             : 
     176             : protected:
     177             :     // Construction/destruction limited to subclasses.
     178             :     KeyValueStoreManager()  = default;
     179             :     ~KeyValueStoreManager() = default;
     180             : 
     181             :     // No copy, move or assignment.
     182             :     KeyValueStoreManager(const KeyValueStoreManager &)             = delete;
     183             :     KeyValueStoreManager(const KeyValueStoreManager &&)            = delete;
     184             :     KeyValueStoreManager & operator=(const KeyValueStoreManager &) = delete;
     185             : };
     186             : 
     187             : /**
     188             :  * Returns a reference to the public interface of the KeyValueStoreManager singleton object.
     189             :  *
     190             :  * chip application should use this to access features of the KeyValueStoreManager object
     191             :  * that are common to all platforms.
     192             :  */
     193             : extern KeyValueStoreManager & KeyValueStoreMgr();
     194             : 
     195             : /**
     196             :  * Returns the platform-specific implementation of the KeyValueStoreManager singleton object.
     197             :  *
     198             :  * chip applications can use this to gain access to features of the KeyValueStoreManager
     199             :  * that are specific to the selected platform.
     200             :  */
     201             : extern KeyValueStoreManagerImpl & KeyValueStoreMgrImpl();
     202             : 
     203             : } // namespace PersistedStorage
     204             : } // namespace DeviceLayer
     205             : } // namespace chip
     206             : 
     207             : /* Include a header file containing the implementation of the KeyValueStoreManager
     208             :  * object for the selected platform.
     209             :  */
     210             : #ifdef EXTERNAL_KEYVALUESTOREMANAGERIMPL_HEADER
     211             : #include EXTERNAL_KEYVALUESTOREMANAGERIMPL_HEADER
     212             : #elif defined(CHIP_DEVICE_LAYER_TARGET)
     213             : #define KEYVALUESTOREMANAGERIMPL_HEADER <platform/CHIP_DEVICE_LAYER_TARGET/KeyValueStoreManagerImpl.h>
     214             : #include KEYVALUESTOREMANAGERIMPL_HEADER
     215             : #endif // defined(CHIP_DEVICE_LAYER_TARGET)
     216             : 
     217             : namespace chip {
     218             : namespace DeviceLayer {
     219             : namespace PersistedStorage {
     220           5 : inline CHIP_ERROR KeyValueStoreManager::Put(const char * key, const void * value, size_t value_size)
     221             : {
     222           5 :     return static_cast<ImplClass *>(this)->_Put(key, value, value_size);
     223             : }
     224             : 
     225          55 : inline CHIP_ERROR KeyValueStoreManager::Get(const char * key, void * buffer, size_t buffer_size, size_t * read_bytes_size,
     226             :                                             size_t offset_bytes)
     227             : {
     228          55 :     return static_cast<ImplClass *>(this)->_Get(key, buffer, buffer_size, read_bytes_size, offset_bytes);
     229             : }
     230             : 
     231           0 : inline CHIP_ERROR KeyValueStoreManager::Delete(const char * key)
     232             : {
     233           0 :     return static_cast<ImplClass *>(this)->_Delete(key);
     234             : }
     235             : 
     236             : } // namespace PersistedStorage
     237             : } // namespace DeviceLayer
     238             : } // namespace chip