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