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 * 57 */ SettingsDriver(Instance & aInstance)58 explicit SettingsDriver(Instance &aInstance) 59 : InstanceLocator(aInstance) 60 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 61 , mFlash(aInstance) 62 #endif 63 { 64 } 65 66 /** 67 * Initializes the settings storage driver. 68 * 69 * @param[in] aSensitiveKeys A pointer to an array containing the list of sensitive keys. 70 * @param[in] aSensitiveKeysLength The number of entries in the @p aSensitiveKeys array. 71 * 72 */ Init(const uint16_t * aSensitiveKeys,uint16_t aSensitiveKeysLength)73 void Init(const uint16_t *aSensitiveKeys, uint16_t aSensitiveKeysLength) 74 { 75 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 76 OT_UNUSED_VARIABLE(aSensitiveKeys); 77 OT_UNUSED_VARIABLE(aSensitiveKeysLength); 78 79 mFlash.Init(); 80 #else 81 otPlatSettingsInit(GetInstancePtr(), aSensitiveKeys, aSensitiveKeysLength); 82 #endif 83 } 84 85 /** 86 * Deinitializes the settings driver. 87 * 88 */ Deinit(void)89 void Deinit(void) 90 { 91 #if !OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 92 otPlatSettingsDeinit(GetInstancePtr()); 93 #endif 94 } 95 96 /** 97 * Adds a value to @p aKey. 98 * 99 * @param[in] aKey The key associated with the value. 100 * @param[in] aValue A pointer to where the new value of the setting should be read from. 101 * MUST NOT be `nullptr` if @p aValueLength is non-zero. 102 * @param[in] aValueLength The length of the data pointed to by @p aValue. May be zero. 103 * 104 * @retval kErrorNone The value was added. 105 * @retval kErrorNoBufs Not enough space to store the value. 106 * 107 */ Add(uint16_t aKey,const void * aValue,uint16_t aValueLength)108 Error Add(uint16_t aKey, const void *aValue, uint16_t aValueLength) 109 { 110 Error error; 111 const uint8_t *value = reinterpret_cast<const uint8_t *>(aValue); 112 113 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 114 error = mFlash.Add(aKey, value, aValueLength); 115 #else 116 error = otPlatSettingsAdd(GetInstancePtr(), aKey, value, aValueLength); 117 #endif 118 return error; 119 } 120 121 /** 122 * Removes a value from @p aKey. 123 * 124 * @param[in] aKey The key associated with the value. 125 * @param[in] aIndex The index of the value to be removed. 126 * If set to -1, all values for @p aKey will be removed. 127 * 128 * @retval kErrorNone The given key and index was found and removed successfully. 129 * @retval kErrorNotFound The given key or index was not found. 130 * 131 */ Delete(uint16_t aKey,int aIndex=-1)132 Error Delete(uint16_t aKey, int aIndex = -1) 133 { 134 Error error; 135 136 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 137 error = mFlash.Delete(aKey, aIndex); 138 #else 139 error = otPlatSettingsDelete(GetInstancePtr(), aKey, aIndex); 140 #endif 141 return error; 142 } 143 144 /** 145 * Fetches the value identified by @p aKey at a given @p aIndex. 146 * 147 * @param[in] aKey The key associated with the requested value. 148 * @param[in] aIndex The index of the specific item to get. 149 * @param[out] aValue A pointer to where the value of the setting should be written. 150 * May be `nullptr` if just testing for the presence or length of a key. 151 * @param[in,out] aValueLength A pointer to the length of the value. 152 * When called, this should point to an integer containing the maximum bytes that 153 * can be written to @p aValue. 154 * At return, the actual length of the setting is written. 155 * May be `nullptr` if performing a presence check. 156 * 157 * @retval kErrorNone The value was fetched successfully. 158 * @retval kErrorNotFound The key was not found. 159 * 160 */ Get(uint16_t aKey,int aIndex,void * aValue,uint16_t * aValueLength) const161 Error Get(uint16_t aKey, int aIndex, void *aValue, uint16_t *aValueLength) const 162 { 163 Error error; 164 uint8_t *value = reinterpret_cast<uint8_t *>(aValue); 165 166 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 167 error = mFlash.Get(aKey, aIndex, value, aValueLength); 168 #else 169 error = otPlatSettingsGet(GetInstancePtr(), aKey, aIndex, value, aValueLength); 170 #endif 171 return error; 172 } 173 174 /** 175 * Fetches the value identified by @p aKey. 176 * 177 * @param[in] aKey The key associated with the requested value. 178 * @param[out] aValue A pointer to where the value of the setting should be written. 179 * May be `nullptr` if just testing for the presence or length of a key. 180 * @param[in,out] aValueLength A pointer to the length of the value. 181 * When called, this should point to an integer containing the maximum bytes that 182 * can be written to @p aValue. 183 * At return, the actual length of the setting is written. 184 * May be `nullptr` if performing a presence check. 185 * 186 * @retval kErrorNone The value was fetched successfully. 187 * @retval kErrorNotFound The key was not found. 188 * 189 */ Get(uint16_t aKey,void * aValue,uint16_t * aValueLength) const190 Error Get(uint16_t aKey, void *aValue, uint16_t *aValueLength) const { return Get(aKey, 0, aValue, aValueLength); } 191 192 /** 193 * Sets or replaces the value identified by @p aKey. 194 * 195 * If there was more than one value previously associated with @p aKey, then they are all deleted and replaced with 196 * this single entry. 197 * 198 * @param[in] aKey The key associated with the value. 199 * @param[in] aValue A pointer to where the new value of the setting should be read from. 200 * MUST NOT be `nullptr` if @p aValueLength is non-zero. 201 * @param[in] aValueLength The length of the data pointed to by @p aValue. May be zero. 202 * 203 * @retval kErrorNone The value was changed. 204 * @retval kErrorNoBufs Not enough space to store the value. 205 * 206 */ Set(uint16_t aKey,const void * aValue,uint16_t aValueLength)207 Error Set(uint16_t aKey, const void *aValue, uint16_t aValueLength) 208 { 209 Error error; 210 const uint8_t *value = reinterpret_cast<const uint8_t *>(aValue); 211 212 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 213 error = mFlash.Set(aKey, value, aValueLength); 214 #else 215 error = otPlatSettingsSet(GetInstancePtr(), aKey, value, aValueLength); 216 #endif 217 return error; 218 } 219 220 /** 221 * Removes all values. 222 * 223 */ Wipe(void)224 void Wipe(void) 225 { 226 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 227 mFlash.Wipe(); 228 #else 229 otPlatSettingsWipe(GetInstancePtr()); 230 #endif 231 } 232 233 private: GetInstancePtr(void) const234 otInstance *GetInstancePtr(void) const { return reinterpret_cast<otInstance *>(&InstanceLocator::GetInstance()); } 235 236 #if OPENTHREAD_CONFIG_PLATFORM_FLASH_API_ENABLE 237 Flash mFlash; 238 #endif 239 }; 240 241 } // namespace ot 242 243 #endif // SETTINGS_DRIVER_HPP_ 244
