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 defines the OpenThread Instance API. 33 */ 34 35 #ifndef OPENTHREAD_INSTANCE_H_ 36 #define OPENTHREAD_INSTANCE_H_ 37 38 #include <stdlib.h> 39 40 #include <openthread/error.h> 41 #include <openthread/platform/logging.h> 42 #include <openthread/platform/toolchain.h> 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * The OpenThread API monotonic version number. 50 * 51 * This number MUST increase by one each time the contents of public OpenThread API include headers change. 52 * 53 * @note This number versions both OpenThread platform and user APIs. 54 * 55 */ 56 #define OPENTHREAD_API_VERSION (419) 57 58 /** 59 * @addtogroup api-instance 60 * 61 * @brief 62 * This module includes functions that control the OpenThread Instance. 63 * 64 * @{ 65 * 66 */ 67 68 /** 69 * Represents the OpenThread instance structure. 70 */ 71 typedef struct otInstance otInstance; 72 73 /** 74 * Initializes the OpenThread library. 75 * 76 * Initializes OpenThread and prepares it for subsequent OpenThread API calls. This function must be 77 * called before any other calls to OpenThread. 78 * 79 * Is available and can only be used when support for multiple OpenThread instances is enabled. 80 * 81 * @param[in] aInstanceBuffer The buffer for OpenThread to use for allocating the otInstance structure. 82 * @param[in,out] aInstanceBufferSize On input, the size of aInstanceBuffer. On output, if not enough space for 83 * otInstance, the number of bytes required for otInstance. 84 * 85 * @returns A pointer to the new OpenThread instance. 86 * 87 * @sa otInstanceFinalize 88 * 89 */ 90 otInstance *otInstanceInit(void *aInstanceBuffer, size_t *aInstanceBufferSize); 91 92 /** 93 * Initializes the static single instance of the OpenThread library. 94 * 95 * Initializes OpenThread and prepares it for subsequent OpenThread API calls. This function must be 96 * called before any other calls to OpenThread. 97 * 98 * Is available and can only be used when support for multiple OpenThread instances is disabled. 99 * 100 * @returns A pointer to the single OpenThread instance. 101 * 102 */ 103 otInstance *otInstanceInitSingle(void); 104 105 /** 106 * Initializes the OpenThread instance. 107 * 108 * This function initializes OpenThread and prepares it for subsequent OpenThread API calls. This function must be 109 * called before any other calls to OpenThread. This method utilizes static buffer to initialize the OpenThread 110 * instance. 111 * 112 * This function is available and can only be used when support for multiple OpenThread static instances is 113 * enabled (`OPENTHREAD_CONFIG_MULTIPLE_STATIC_INSTANCE_ENABLE`) 114 * 115 * @param[in] aIdx The index of the OpenThread instance to initialize. 116 * 117 * @returns A pointer to the new OpenThread instance. 118 * 119 */ 120 otInstance *otInstanceInitMultiple(uint8_t aIdx); 121 122 /** 123 * Gets the instance identifier. 124 * 125 * The instance identifier is set to a random value when the instance is constructed, and then its value will not 126 * change after initialization. 127 * 128 * @returns The instance identifier. 129 * 130 */ 131 uint32_t otInstanceGetId(otInstance *aInstance); 132 133 /** 134 * Indicates whether or not the instance is valid/initialized. 135 * 136 * The instance is considered valid if it is acquired and initialized using either `otInstanceInitSingle()` (in single 137 * instance case) or `otInstanceInit()` (in multi instance case). A subsequent call to `otInstanceFinalize()` causes 138 * the instance to be considered as uninitialized. 139 * 140 * @param[in] aInstance A pointer to an OpenThread instance. 141 * 142 * @returns TRUE if the given instance is valid/initialized, FALSE otherwise. 143 * 144 */ 145 bool otInstanceIsInitialized(otInstance *aInstance); 146 147 /** 148 * Disables the OpenThread library. 149 * 150 * Call this function when OpenThread is no longer in use. 151 * 152 * @param[in] aInstance A pointer to an OpenThread instance. 153 * 154 */ 155 void otInstanceFinalize(otInstance *aInstance); 156 157 /** 158 * Returns the current instance uptime (in msec). 159 * 160 * Requires `OPENTHREAD_CONFIG_UPTIME_ENABLE` to be enabled. 161 * 162 * The uptime is given as number of milliseconds since OpenThread instance was initialized. 163 * 164 * @param[in] aInstance A pointer to an OpenThread instance. 165 * 166 * @returns The uptime (number of milliseconds). 167 * 168 */ 169 uint64_t otInstanceGetUptime(otInstance *aInstance); 170 171 #define OT_UPTIME_STRING_SIZE 24 ///< Recommended size for string representation of uptime. 172 173 /** 174 * Returns the current instance uptime as a human-readable string. 175 * 176 * Requires `OPENTHREAD_CONFIG_UPTIME_ENABLE` to be enabled. 177 * 178 * The string follows the format "<hh>:<mm>:<ss>.<mmmm>" for hours, minutes, seconds and millisecond (if uptime is 179 * shorter than one day) or "<dd>d.<hh>:<mm>:<ss>.<mmmm>" (if longer than a day). 180 * 181 * If the resulting string does not fit in @p aBuffer (within its @p aSize characters), the string will be truncated 182 * but the outputted string is always null-terminated. 183 * 184 * @param[in] aInstance A pointer to an OpenThread instance. 185 * @param[out] aBuffer A pointer to a char array to output the string. 186 * @param[in] aSize The size of @p aBuffer (in bytes). Recommended to use `OT_UPTIME_STRING_SIZE`. 187 * 188 */ 189 void otInstanceGetUptimeAsString(otInstance *aInstance, char *aBuffer, uint16_t aSize); 190 191 #define OT_CHANGED_IP6_ADDRESS_ADDED (1U << 0) ///< IPv6 address was added 192 #define OT_CHANGED_IP6_ADDRESS_REMOVED (1U << 1) ///< IPv6 address was removed 193 #define OT_CHANGED_THREAD_ROLE (1U << 2) ///< Role (disabled, detached, child, router, leader) changed 194 #define OT_CHANGED_THREAD_LL_ADDR (1U << 3) ///< The link-local address changed 195 #define OT_CHANGED_THREAD_ML_ADDR (1U << 4) ///< The mesh-local address changed 196 #define OT_CHANGED_THREAD_RLOC_ADDED (1U << 5) ///< RLOC was added 197 #define OT_CHANGED_THREAD_RLOC_REMOVED (1U << 6) ///< RLOC was removed 198 #define OT_CHANGED_THREAD_PARTITION_ID (1U << 7) ///< Partition ID changed 199 #define OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER (1U << 8) ///< Thread Key Sequence changed 200 #define OT_CHANGED_THREAD_NETDATA (1U << 9) ///< Thread Network Data changed 201 #define OT_CHANGED_THREAD_CHILD_ADDED (1U << 10) ///< Child was added 202 #define OT_CHANGED_THREAD_CHILD_REMOVED (1U << 11) ///< Child was removed 203 #define OT_CHANGED_IP6_MULTICAST_SUBSCRIBED (1U << 12) ///< Subscribed to a IPv6 multicast address 204 #define OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED (1U << 13) ///< Unsubscribed from a IPv6 multicast address 205 #define OT_CHANGED_THREAD_CHANNEL (1U << 14) ///< Thread network channel changed 206 #define OT_CHANGED_THREAD_PANID (1U << 15) ///< Thread network PAN Id changed 207 #define OT_CHANGED_THREAD_NETWORK_NAME (1U << 16) ///< Thread network name changed 208 #define OT_CHANGED_THREAD_EXT_PANID (1U << 17) ///< Thread network extended PAN ID changed 209 #define OT_CHANGED_NETWORK_KEY (1U << 18) ///< Network key changed 210 #define OT_CHANGED_PSKC (1U << 19) ///< PSKc changed 211 #define OT_CHANGED_SECURITY_POLICY (1U << 20) ///< Security Policy changed 212 #define OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL (1U << 21) ///< Channel Manager new pending Thread channel changed 213 #define OT_CHANGED_SUPPORTED_CHANNEL_MASK (1U << 22) ///< Supported channel mask changed 214 #define OT_CHANGED_COMMISSIONER_STATE (1U << 23) ///< Commissioner state changed 215 #define OT_CHANGED_THREAD_NETIF_STATE (1U << 24) ///< Thread network interface state changed 216 #define OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE (1U << 25) ///< Backbone Router state changed 217 #define OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL (1U << 26) ///< Local Backbone Router configuration changed 218 #define OT_CHANGED_JOINER_STATE (1U << 27) ///< Joiner state changed 219 #define OT_CHANGED_ACTIVE_DATASET (1U << 28) ///< Active Operational Dataset changed 220 #define OT_CHANGED_PENDING_DATASET (1U << 29) ///< Pending Operational Dataset changed 221 #define OT_CHANGED_NAT64_TRANSLATOR_STATE (1U << 30) ///< The state of NAT64 translator changed 222 #define OT_CHANGED_PARENT_LINK_QUALITY (1U << 31) ///< Parent link quality changed 223 224 /** 225 * Represents a bit-field indicating specific state/configuration that has changed. See `OT_CHANGED_*` 226 * definitions. 227 * 228 */ 229 typedef uint32_t otChangedFlags; 230 231 /** 232 * Pointer is called to notify certain configuration or state changes within OpenThread. 233 * 234 * @param[in] aFlags A bit-field indicating specific state that has changed. See `OT_CHANGED_*` definitions. 235 * @param[in] aContext A pointer to application-specific context. 236 * 237 */ 238 typedef void (*otStateChangedCallback)(otChangedFlags aFlags, void *aContext); 239 240 /** 241 * Registers a callback to indicate when certain configuration or state changes within OpenThread. 242 * 243 * @param[in] aInstance A pointer to an OpenThread instance. 244 * @param[in] aCallback A pointer to a function that is called with certain configuration or state changes. 245 * @param[in] aContext A pointer to application-specific context. 246 * 247 * @retval OT_ERROR_NONE Added the callback to the list of callbacks. 248 * @retval OT_ERROR_ALREADY The callback was already registered. 249 * @retval OT_ERROR_NO_BUFS Could not add the callback due to resource constraints. 250 * 251 */ 252 otError otSetStateChangedCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext); 253 254 /** 255 * Removes a callback to indicate when certain configuration or state changes within OpenThread. 256 * 257 * @param[in] aInstance A pointer to an OpenThread instance. 258 * @param[in] aCallback A pointer to a function that is called with certain configuration or state changes. 259 * @param[in] aContext A pointer to application-specific context. 260 * 261 */ 262 void otRemoveStateChangeCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext); 263 264 /** 265 * Triggers a platform reset. 266 * 267 * The reset process ensures that all the OpenThread state/info (stored in volatile memory) is erased. Note that the 268 * `otPlatformReset` does not erase any persistent state/info saved in non-volatile memory. 269 * 270 * @param[in] aInstance A pointer to an OpenThread instance. 271 * 272 */ 273 void otInstanceReset(otInstance *aInstance); 274 275 /** 276 * Triggers a platform reset to bootloader mode, if supported. 277 * 278 * Requires `OPENTHREAD_CONFIG_PLATFORM_BOOTLOADER_MODE_ENABLE`. 279 * 280 * @param[in] aInstance A pointer to an OpenThread instance. 281 * 282 * @retval OT_ERROR_NONE Reset to bootloader successfully. 283 * @retval OT_ERROR_BUSY Failed due to another operation is ongoing. 284 * @retval OT_ERROR_NOT_CAPABLE Not capable of resetting to bootloader. 285 * 286 */ 287 otError otInstanceResetToBootloader(otInstance *aInstance); 288 289 /** 290 * Deletes all the settings stored on non-volatile memory, and then triggers a platform reset. 291 * 292 * @param[in] aInstance A pointer to an OpenThread instance. 293 * 294 */ 295 void otInstanceFactoryReset(otInstance *aInstance); 296 297 /** 298 * Resets the internal states of the OpenThread radio stack. 299 * 300 * Callbacks and configurations are preserved. 301 * 302 * This API is only available under radio builds (`OPENTHREAD_RADIO = 1`). 303 * 304 * @param[in] aInstance A pointer to an OpenThread instance. 305 * 306 */ 307 void otInstanceResetRadioStack(otInstance *aInstance); 308 309 /** 310 * Erases all the OpenThread persistent info (network settings) stored on non-volatile memory. 311 * Erase is successful only if the device is in `disabled` state/role. 312 * 313 * @param[in] aInstance A pointer to an OpenThread instance. 314 * 315 * @retval OT_ERROR_NONE All persistent info/state was erased successfully. 316 * @retval OT_ERROR_INVALID_STATE Device is not in `disabled` state/role. 317 * 318 */ 319 otError otInstanceErasePersistentInfo(otInstance *aInstance); 320 321 /** 322 * Gets the OpenThread version string. 323 * 324 * @returns A pointer to the OpenThread version. 325 * 326 */ 327 const char *otGetVersionString(void); 328 329 /** 330 * Gets the OpenThread radio version string. 331 * 332 * @param[in] aInstance A pointer to an OpenThread instance. 333 * 334 * @returns A pointer to the OpenThread radio version. 335 * 336 */ 337 const char *otGetRadioVersionString(otInstance *aInstance); 338 339 /** 340 * @} 341 * 342 */ 343 344 #ifdef __cplusplus 345 } // extern "C" 346 #endif 347 348 #endif // OPENTHREAD_INSTANCE_H_ 349
