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