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 (230) 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 }; 200 201 /** 202 * This type represents a bit-field indicating specific state/configuration that has changed. See `OT_CHANGED_*` 203 * definitions. 204 * 205 */ 206 typedef uint32_t otChangedFlags; 207 208 /** 209 * This function pointer is called to notify certain configuration or state changes within OpenThread. 210 * 211 * @param[in] aFlags A bit-field indicating specific state that has changed. See `OT_CHANGED_*` definitions. 212 * @param[in] aContext A pointer to application-specific context. 213 * 214 */ 215 typedef void (*otStateChangedCallback)(otChangedFlags aFlags, void *aContext); 216 217 /** 218 * This function registers a callback to indicate when certain configuration or state changes within OpenThread. 219 * 220 * @param[in] aInstance A pointer to an OpenThread instance. 221 * @param[in] aCallback A pointer to a function that is called with certain configuration or state changes. 222 * @param[in] aContext A pointer to application-specific context. 223 * 224 * @retval OT_ERROR_NONE Added the callback to the list of callbacks. 225 * @retval OT_ERROR_ALREADY The callback was already registered. 226 * @retval OT_ERROR_NO_BUFS Could not add the callback due to resource constraints. 227 * 228 */ 229 otError otSetStateChangedCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext); 230 231 /** 232 * This function removes a callback to indicate when certain configuration or state changes within OpenThread. 233 * 234 * @param[in] aInstance A pointer to an OpenThread instance. 235 * @param[in] aCallback A pointer to a function that is called with certain configuration or state changes. 236 * @param[in] aContext A pointer to application-specific context. 237 * 238 */ 239 void otRemoveStateChangeCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext); 240 241 /** 242 * This method triggers a platform reset. 243 * 244 * The reset process ensures that all the OpenThread state/info (stored in volatile memory) is erased. Note that the 245 * `otPlatformReset` does not erase any persistent state/info saved in non-volatile memory. 246 * 247 * @param[in] aInstance A pointer to an OpenThread instance. 248 * 249 */ 250 void otInstanceReset(otInstance *aInstance); 251 252 /** 253 * This method deletes all the settings stored on non-volatile memory, and then triggers platform reset. 254 * 255 * @param[in] aInstance A pointer to an OpenThread instance. 256 * 257 */ 258 void otInstanceFactoryReset(otInstance *aInstance); 259 260 /** 261 * This method resets the internal states of the OpenThread radio stack. 262 * 263 * Callbacks and configurations are preserved. 264 * 265 * This API is only available under radio builds (`OPENTHREAD_RADIO = 1`). 266 * 267 * @param[in] aInstance A pointer to an OpenThread instance. 268 * 269 */ 270 void otInstanceResetRadioStack(otInstance *aInstance); 271 272 /** 273 * This function erases all the OpenThread persistent info (network settings) stored on non-volatile memory. 274 * Erase is successful only if the device is in `disabled` state/role. 275 * 276 * @param[in] aInstance A pointer to an OpenThread instance. 277 * 278 * @retval OT_ERROR_NONE All persistent info/state was erased successfully. 279 * @retval OT_ERROR_INVALID_STATE Device is not in `disabled` state/role. 280 * 281 */ 282 otError otInstanceErasePersistentInfo(otInstance *aInstance); 283 284 /** 285 * This function gets the OpenThread version string. 286 * 287 * @returns A pointer to the OpenThread version. 288 * 289 */ 290 const char *otGetVersionString(void); 291 292 /** 293 * This function gets the OpenThread radio version string. 294 * 295 * @param[in] aInstance A pointer to an OpenThread instance. 296 * 297 * @returns A pointer to the OpenThread radio version. 298 * 299 */ 300 const char *otGetRadioVersionString(otInstance *aInstance); 301 302 /** 303 * @} 304 * 305 */ 306 307 #ifdef __cplusplus 308 } // extern "C" 309 #endif 310 311 #endif // OPENTHREAD_INSTANCE_H_ 312