src/include/platform/PersistedStorage.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2016-2017 Nest Labs, Inc.
   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 /**
  20  * @file
  21  *
  22  * @brief
  23  *   API function declarations for reading from and writing to persistent storage.
  24  *   Platforms will be responsible for implementing the read/write details.
  25  */
  26
  27 #pragma once
  28
  29 #include <climits>
  30 #include <cstddef>
  31 #include <cstdint>
  32 #include <type_traits>
  33
  34 #include <core/CHIPConfig.h>
  35 #include <core/CHIPError.h>
  36
  37 namespace chip {
  38 namespace Platform {
  39 namespace PersistedStorage {
  40
  41 // Persistent storage key type is const char * in core config, however
  42 // it is uint8_t/uint16_t on other platforms (EFR32 and nRF5 respectively)
  43 typedef CHIP_CONFIG_PERSISTED_STORAGE_KEY_TYPE Key;
  44
  45 namespace internal {
  46 template <typename T>
  47 struct EmptyKey
  48 {
  49     static constexpr T value = 0; // handles numeric values
  50 };
  51
  52 template <>
  53 struct EmptyKey<const char *>
  54 {
  55     static constexpr const char * value = nullptr;
  56 };
  57
  58 } // namespace internal
  59
  60 constexpr Key kEmptyKey = internal::EmptyKey<Key>::value;
  61
  62 /**
  63  *  @brief
  64  *    Read integer value of a key from persistent storage.
  65  *    Platform is responsible for validating aKey.
  66  *
  67  *  @param[in]     aKey      A key to a persistently-stored value.
  68  *  @param[in,out] aValue    A reference to an integer value.
  69  *
  70  *  @return CHIP_ERROR_INVALID_ARGUMENT if aKey is NULL
  71  *          CHIP_ERROR_INVALID_STRING_LENGTH if aKey exceeds
  72  *                  CHIP_CONFIG_PERSISTED_STORAGE_MAX_KEY_LENGTH
  73  *          CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND if aKey does not exist
  74  *          CHIP_NO_ERROR otherwise
  75  */
  76 CHIP_ERROR Read(Key aKey, uint32_t & aValue);
  77
  78 /**
  79  *  @brief
  80  *    Write the integer value of a key to persistent storage.
  81  *    Platform is responsible for validating aKey.
  82  *    If aKey does not exist, it will be created and assigned aValue.
  83  *    Otherwise any existing value of aKey will be replaced with aValue.
  84  *
  85  *  @param[in] aKey      A key to a persistently-stored value.
  86  *  @param[in] aValue    The value.
  87  *
  88  *  @return CHIP_ERROR_INVALID_ARGUMENT if aKey is NULL
  89  *          CHIP_ERROR_INVALID_STRING_LENGTH if aKey exceeds
  90  *                  CHIP_CONFIG_PERSISTED_STORAGE_MAX_KEY_LENGTH
  91  *          CHIP_NO_ERROR otherwise
  92  */
  93 CHIP_ERROR Write(Key aKey, uint32_t aValue);
  94
  95 } // namespace PersistedStorage
  96 } // namespace Platform
  97 } // namespace chip