1 /* 2 * Copyright (c) 2016, 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 * @brief 32 * This file includes platform abstraction for non-volatile storage of settings. 33 */ 34 35 #ifndef OPENTHREAD_PLATFORM_SETTINGS_H_ 36 #define OPENTHREAD_PLATFORM_SETTINGS_H_ 37 38 #include <openthread/instance.h> 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /** 45 * @addtogroup plat-settings 46 * 47 * @brief 48 * This module includes the platform abstraction for non-volatile storage of settings. 49 * 50 * @{ 51 * 52 */ 53 54 /** 55 * This enumeration defines the keys of settings. 56 * 57 * Note: When adding a new setings key, if the settings corresponding to the key contains security sensitive 58 * information, the developer MUST add the key to the array `kCriticalKeys`. 59 * 60 */ 61 enum 62 { 63 OT_SETTINGS_KEY_ACTIVE_DATASET = 0x0001, ///< Active Operational Dataset. 64 OT_SETTINGS_KEY_PENDING_DATASET = 0x0002, ///< Pending Operational Dataset. 65 OT_SETTINGS_KEY_NETWORK_INFO = 0x0003, ///< Thread network information. 66 OT_SETTINGS_KEY_PARENT_INFO = 0x0004, ///< Parent information. 67 OT_SETTINGS_KEY_CHILD_INFO = 0x0005, ///< Child information. 68 OT_SETTINGS_KEY_RESERVED = 0x0006, ///< Reserved (previously auto-start). 69 OT_SETTINGS_KEY_SLAAC_IID_SECRET_KEY = 0x0007, ///< SLAAC key to generate semantically opaque IID. 70 OT_SETTINGS_KEY_DAD_INFO = 0x0008, ///< Duplicate Address Detection (DAD) information. 71 OT_SETTINGS_KEY_OMR_PREFIX = 0x0009, ///< Off-mesh routable (OMR) prefix. 72 OT_SETTINGS_KEY_ON_LINK_PREFIX = 0x000a, ///< On-link prefix for infrastructure link. 73 OT_SETTINGS_KEY_SRP_ECDSA_KEY = 0x000b, ///< SRP client ECDSA public/private key pair. 74 OT_SETTINGS_KEY_SRP_CLIENT_INFO = 0x000c, ///< The SRP client info (selected SRP server address). 75 OT_SETTINGS_KEY_SRP_SERVER_INFO = 0x000d, ///< The SRP server info (UDP port). 76 }; 77 78 /** 79 * Performs any initialization for the settings subsystem, if necessary. 80 * 81 * @param[in] aInstance The OpenThread instance structure. 82 * 83 */ 84 void otPlatSettingsInit(otInstance *aInstance); 85 86 /** 87 * Performs any de-initialization for the settings subsystem, if necessary. 88 * 89 * @param[in] aInstance The OpenThread instance structure. 90 * 91 */ 92 void otPlatSettingsDeinit(otInstance *aInstance); 93 94 /** 95 * This function sets the critical keys that should be stored in the secure area. 96 * 97 * Note that the memory pointed by @p aKeys MUST not be released before @p aInstance is destroyed. 98 * 99 * @param[in] aInstance The OpenThread instance structure. 100 * @param[in] aKeys A pointer to an array containing the list of critical keys. 101 * @param[in] aKeysLength The number of entries in the @p aKeys array. 102 * 103 */ 104 void otPlatSettingsSetCriticalKeys(otInstance *aInstance, const uint16_t *aKeys, uint16_t aKeysLength); 105 106 /// Fetches the value of a setting 107 /** This function fetches the value of the setting identified 108 * by aKey and write it to the memory pointed to by aValue. 109 * It then writes the length to the integer pointed to by 110 * aValueLength. The initial value of aValueLength is the 111 * maximum number of bytes to be written to aValue. 112 * 113 * This function can be used to check for the existence of 114 * a key without fetching the value by setting aValue and 115 * aValueLength to NULL. You can also check the length of 116 * the setting without fetching it by setting only aValue 117 * to NULL. 118 * 119 * Note that the underlying storage implementation is not 120 * required to maintain the order of settings with multiple 121 * values. The order of such values MAY change after ANY 122 * write operation to the store. 123 * 124 * @param[in] aInstance The OpenThread instance structure. 125 * @param[in] aKey The key associated with the requested setting. 126 * @param[in] aIndex The index of the specific item to get. 127 * @param[out] aValue A pointer to where the value of the setting should be written. May be set to NULL if 128 * just testing for the presence or length of a setting. 129 * @param[inout] aValueLength A pointer to the length of the value. When called, this pointer should point to an 130 * integer containing the maximum value size that can be written to aValue. At return, 131 * the actual length of the setting is written. This may be set to NULL if performing 132 * a presence check. 133 * 134 * @retval OT_ERROR_NONE The given setting was found and fetched successfully. 135 * @retval OT_ERROR_NOT_FOUND The given setting was not found in the setting store. 136 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 137 */ 138 otError otPlatSettingsGet(otInstance *aInstance, uint16_t aKey, int aIndex, uint8_t *aValue, uint16_t *aValueLength); 139 140 /// Sets or replaces the value of a setting 141 /** This function sets or replaces the value of a setting 142 * identified by aKey. If there was more than one 143 * value previously associated with aKey, then they are 144 * all deleted and replaced with this single entry. 145 * 146 * Calling this function successfully may cause unrelated 147 * settings with multiple values to be reordered. 148 * 149 * @param[in] aInstance The OpenThread instance structure. 150 * @param[in] aKey The key associated with the setting to change. 151 * @param[in] aValue A pointer to where the new value of the setting should be read from. MUST NOT be NULL if 152 * aValueLength is non-zero. 153 * @param[in] aValueLength The length of the data pointed to by aValue. May be zero. 154 * 155 * @retval OT_ERROR_NONE The given setting was changed or staged. 156 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 157 * @retval OT_ERROR_NO_BUFS No space remaining to store the given setting. 158 */ 159 otError otPlatSettingsSet(otInstance *aInstance, uint16_t aKey, const uint8_t *aValue, uint16_t aValueLength); 160 161 /// Adds a value to a setting 162 /** This function adds the value to a setting 163 * identified by aKey, without replacing any existing 164 * values. 165 * 166 * Note that the underlying implementation is not required 167 * to maintain the order of the items associated with a 168 * specific key. The added value may be added to the end, 169 * the beginning, or even somewhere in the middle. The order 170 * of any pre-existing values may also change. 171 * 172 * Calling this function successfully may cause unrelated 173 * settings with multiple values to be reordered. 174 * 175 * @param[in] aInstance The OpenThread instance structure. 176 * @param[in] aKey The key associated with the setting to change. 177 * @param[in] aValue A pointer to where the new value of the setting should be read from. MUST NOT be NULL 178 * if aValueLength is non-zero. 179 * @param[in] aValueLength The length of the data pointed to by aValue. May be zero. 180 * 181 * @retval OT_ERROR_NONE The given setting was added or staged to be added. 182 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 183 * @retval OT_ERROR_NO_BUFS No space remaining to store the given setting. 184 */ 185 otError otPlatSettingsAdd(otInstance *aInstance, uint16_t aKey, const uint8_t *aValue, uint16_t aValueLength); 186 187 /// Removes a setting from the setting store 188 /** This function deletes a specific value from the 189 * setting identified by aKey from the settings store. 190 * 191 * Note that the underlying implementation is not required 192 * to maintain the order of the items associated with a 193 * specific key. 194 * 195 * @param[in] aInstance The OpenThread instance structure. 196 * @param[in] aKey The key associated with the requested setting. 197 * @param[in] aIndex The index of the value to be removed. If set to -1, all values for this aKey will be removed. 198 * 199 * @retval OT_ERROR_NONE The given key and index was found and removed successfully. 200 * @retval OT_ERROR_NOT_FOUND The given key or index was not found in the setting store. 201 * @retval OT_ERROR_NOT_IMPLEMENTED This function is not implemented on this platform. 202 */ 203 otError otPlatSettingsDelete(otInstance *aInstance, uint16_t aKey, int aIndex); 204 205 /// Removes all settings from the setting store 206 /** This function deletes all settings from the settings 207 * store, resetting it to its initial factory state. 208 * 209 * @param[in] aInstance The OpenThread instance structure. 210 */ 211 void otPlatSettingsWipe(otInstance *aInstance); 212 213 /** 214 * @} 215 * 216 */ 217 218 #ifdef __cplusplus 219 } // extern "C" 220 #endif 221 222 #endif // OPENTHREAD_PLATFORM_SETTINGS_H_ 223
