1 /* 2 * Copyright (c) 2016-21, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * This file includes definitions for settings driver. 32 */ 33 34 #ifndef SETTINGS_DRIVER_HPP_ 35 #define SETTINGS_DRIVER_HPP_ 36 37 #include "openthread-core-config.h" 38 39 #include <openthread/platform/settings.h> 40 41 #include "common/encoding.hpp" 42 #include "common/error.hpp" 43 #include "common/locator.hpp" 44 #include "common/non_copyable.hpp" 45 #include "utils/flash.hpp" 46 47 namespace ot { 48 49 class SettingsDriver : public InstanceLocator, private NonCopyable 50 { 51 public: 52 /** 53 * Initializes the `SettingsDriver`. 54 * 55 * @param[in] aInstance A reference to the OpenThread instance. 56 */ SettingsDriver(Instance & aInstance)57 explicit SettingsDriver(Instance &aInstance) 58 : InstanceLocator(aInstance) 59 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 60 , mFlash(aInstance) 61 #endif 62 { 63 } 64 65 /** 66 * Initializes the settings storage driver. 67 * 68 * @param[in] aSensitiveKeys A pointer to an array containing the list of sensitive keys. 69 * @param[in] aSensitiveKeysLength The number of entries in the @p aSensitiveKeys array. 70 */ Init(const uint16_t * aSensitiveKeys,uint16_t aSensitiveKeysLength)71 void Init(const uint16_t *aSensitiveKeys, uint16_t aSensitiveKeysLength) 72 { 73 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 74 OT_UNUSED_VARIABLE(aSensitiveKeys); 75 OT_UNUSED_VARIABLE(aSensitiveKeysLength); 76 77 mFlash.Init(); 78 #else 79 otPlatSettingsInit(GetInstancePtr(), aSensitiveKeys, aSensitiveKeysLength); 80 #endif 81 } 82 83 /** 84 * Deinitializes the settings driver. 85 */ Deinit(void)86 void Deinit(void) 87 { 88 #if !OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 89 otPlatSettingsDeinit(GetInstancePtr()); 90 #endif 91 } 92 93 /** 94 * Adds a value to @p aKey. 95 * 96 * @param[in] aKey The key associated with the value. 97 * @param[in] aValue A pointer to where the new value of the setting should be read from. 98 * MUST NOT be `nullptr` if @p aValueLength is non-zero. 99 * @param[in] aValueLength The length of the data pointed to by @p aValue. May be zero. 100 * 101 * @retval kErrorNone The value was added. 102 * @retval kErrorNoBufs Not enough space to store the value. 103 */ Add(uint16_t aKey,const void * aValue,uint16_t aValueLength)104 Error Add(uint16_t aKey, const void *aValue, uint16_t aValueLength) 105 { 106 Error error; 107 const uint8_t *value = reinterpret_cast<const uint8_t *>(aValue); 108 109 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 110 error = mFlash.Add(aKey, value, aValueLength); 111 #else 112 error = otPlatSettingsAdd(GetInstancePtr(), aKey, value, aValueLength); 113 #endif 114 return error; 115 } 116 117 /** 118 * Removes a value from @p aKey. 119 * 120 * @param[in] aKey The key associated with the value. 121 * @param[in] aIndex The index of the value to be removed. 122 * If set to -1, all values for @p aKey will be removed. 123 * 124 * @retval kErrorNone The given key and index was found and removed successfully. 125 * @retval kErrorNotFound The given key or index was not found. 126 */ Delete(uint16_t aKey,int aIndex=-1)127 Error Delete(uint16_t aKey, int aIndex = -1) 128 { 129 Error error; 130 131 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 132 error = mFlash.Delete(aKey, aIndex); 133 #else 134 error = otPlatSettingsDelete(GetInstancePtr(), aKey, aIndex); 135 #endif 136 return error; 137 } 138 139 /** 140 * Fetches the value identified by @p aKey at a given @p aIndex. 141 * 142 * @param[in] aKey The key associated with the requested value. 143 * @param[in] aIndex The index of the specific item to get. 144 * @param[out] aValue A pointer to where the value of the setting should be written. 145 * May be `nullptr` if just testing for the presence or length of a key. 146 * @param[in,out] aValueLength A pointer to the length of the value. 147 * When called, this should point to an integer containing the maximum bytes that 148 * can be written to @p aValue. 149 * At return, the actual length of the setting is written. 150 * May be `nullptr` if performing a presence check. 151 * 152 * @retval kErrorNone The value was fetched successfully. 153 * @retval kErrorNotFound The key was not found. 154 */ Get(uint16_t aKey,int aIndex,void * aValue,uint16_t * aValueLength) const155 Error Get(uint16_t aKey, int aIndex, void *aValue, uint16_t *aValueLength) const 156 { 157 Error error; 158 uint8_t *value = reinterpret_cast<uint8_t *>(aValue); 159 160 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 161 error = mFlash.Get(aKey, aIndex, value, aValueLength); 162 #else 163 error = otPlatSettingsGet(GetInstancePtr(), aKey, aIndex, value, aValueLength); 164 #endif 165 return error; 166 } 167 168 /** 169 * Fetches the value identified by @p aKey. 170 * 171 * @param[in] aKey The key associated with the requested value. 172 * @param[out] aValue A pointer to where the value of the setting should be written. 173 * May be `nullptr` if just testing for the presence or length of a key. 174 * @param[in,out] aValueLength A pointer to the length of the value. 175 * When called, this should point to an integer containing the maximum bytes that 176 * can be written to @p aValue. 177 * At return, the actual length of the setting is written. 178 * May be `nullptr` if performing a presence check. 179 * 180 * @retval kErrorNone The value was fetched successfully. 181 * @retval kErrorNotFound The key was not found. 182 */ Get(uint16_t aKey,void * aValue,uint16_t * aValueLength) const183 Error Get(uint16_t aKey, void *aValue, uint16_t *aValueLength) const { return Get(aKey, 0, aValue, aValueLength); } 184 185 /** 186 * Sets or replaces the value identified by @p aKey. 187 * 188 * If there was more than one value previously associated with @p aKey, then they are all deleted and replaced with 189 * this single entry. 190 * 191 * @param[in] aKey The key associated with the value. 192 * @param[in] aValue A pointer to where the new value of the setting should be read from. 193 * MUST NOT be `nullptr` if @p aValueLength is non-zero. 194 * @param[in] aValueLength The length of the data pointed to by @p aValue. May be zero. 195 * 196 * @retval kErrorNone The value was changed. 197 * @retval kErrorNoBufs Not enough space to store the value. 198 */ Set(uint16_t aKey,const void * aValue,uint16_t aValueLength)199 Error Set(uint16_t aKey, const void *aValue, uint16_t aValueLength) 200 { 201 Error error; 202 const uint8_t *value = reinterpret_cast<const uint8_t *>(aValue); 203 204 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 205 error = mFlash.Set(aKey, value, aValueLength); 206 #else 207 error = otPlatSettingsSet(GetInstancePtr(), aKey, value, aValueLength); 208 #endif 209 return error; 210 } 211 212 /** 213 * Removes all values. 214 */ Wipe(void)215 void Wipe(void) 216 { 217 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 218 mFlash.Wipe(); 219 #else 220 otPlatSettingsWipe(GetInstancePtr()); 221 #endif 222 } 223 224 private: GetInstancePtr(void) const225 otInstance *GetInstancePtr(void) const { return reinterpret_cast<otInstance *>(&InstanceLocator::GetInstance()); } 226 227 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 228 Flash mFlash; 229 #endif 230 }; 231 232 } // namespace ot 233 234 #endif // SETTINGS_DRIVER_HPP_ 235