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