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 (158) 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[inout] 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 enumeration defines flags that are passed as part of `otStateChangedCallback`. 131 * 132 */ 133 enum 134 { 135 OT_CHANGED_IP6_ADDRESS_ADDED = 1 << 0, ///< IPv6 address was added 136 OT_CHANGED_IP6_ADDRESS_REMOVED = 1 << 1, ///< IPv6 address was removed 137 OT_CHANGED_THREAD_ROLE = 1 << 2, ///< Role (disabled, detached, child, router, leader) changed 138 OT_CHANGED_THREAD_LL_ADDR = 1 << 3, ///< The link-local address changed 139 OT_CHANGED_THREAD_ML_ADDR = 1 << 4, ///< The mesh-local address changed 140 OT_CHANGED_THREAD_RLOC_ADDED = 1 << 5, ///< RLOC was added 141 OT_CHANGED_THREAD_RLOC_REMOVED = 1 << 6, ///< RLOC was removed 142 OT_CHANGED_THREAD_PARTITION_ID = 1 << 7, ///< Partition ID changed 143 OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER = 1 << 8, ///< Thread Key Sequence changed 144 OT_CHANGED_THREAD_NETDATA = 1 << 9, ///< Thread Network Data changed 145 OT_CHANGED_THREAD_CHILD_ADDED = 1 << 10, ///< Child was added 146 OT_CHANGED_THREAD_CHILD_REMOVED = 1 << 11, ///< Child was removed 147 OT_CHANGED_IP6_MULTICAST_SUBSCRIBED = 1 << 12, ///< Subscribed to a IPv6 multicast address 148 OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED = 1 << 13, ///< Unsubscribed from a IPv6 multicast address 149 OT_CHANGED_THREAD_CHANNEL = 1 << 14, ///< Thread network channel changed 150 OT_CHANGED_THREAD_PANID = 1 << 15, ///< Thread network PAN Id changed 151 OT_CHANGED_THREAD_NETWORK_NAME = 1 << 16, ///< Thread network name changed 152 OT_CHANGED_THREAD_EXT_PANID = 1 << 17, ///< Thread network extended PAN ID changed 153 OT_CHANGED_NETWORK_KEY = 1 << 18, ///< Network key changed 154 OT_CHANGED_PSKC = 1 << 19, ///< PSKc changed 155 OT_CHANGED_SECURITY_POLICY = 1 << 20, ///< Security Policy changed 156 OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL = 1 << 21, ///< Channel Manager new pending Thread channel changed 157 OT_CHANGED_SUPPORTED_CHANNEL_MASK = 1 << 22, ///< Supported channel mask changed 158 OT_CHANGED_COMMISSIONER_STATE = 1 << 23, ///< Commissioner state changed 159 OT_CHANGED_THREAD_NETIF_STATE = 1 << 24, ///< Thread network interface state changed 160 OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE = 1 << 25, ///< Backbone Router state changed 161 OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL = 1 << 26, ///< Local Backbone Router configuration changed 162 OT_CHANGED_JOINER_STATE = 1 << 27, ///< Joiner state changed 163 OT_CHANGED_ACTIVE_DATASET = 1 << 28, ///< Active Operational Dataset changed 164 OT_CHANGED_PENDING_DATASET = 1 << 29, ///< Pending Operational Dataset changed 165 }; 166 167 /** 168 * This type represents a bit-field indicating specific state/configuration that has changed. See `OT_CHANGED_*` 169 * definitions. 170 * 171 */ 172 typedef uint32_t otChangedFlags; 173 174 /** 175 * This function pointer is called to notify certain configuration or state changes within OpenThread. 176 * 177 * @param[in] aFlags A bit-field indicating specific state that has changed. See `OT_CHANGED_*` definitions. 178 * @param[in] aContext A pointer to application-specific context. 179 * 180 */ 181 typedef void (*otStateChangedCallback)(otChangedFlags aFlags, void *aContext); 182 183 /** 184 * This function registers a callback to indicate when certain configuration or state changes within OpenThread. 185 * 186 * @param[in] aInstance A pointer to an OpenThread instance. 187 * @param[in] aCallback A pointer to a function that is called with certain configuration or state changes. 188 * @param[in] aContext A pointer to application-specific context. 189 * 190 * @retval OT_ERROR_NONE Added the callback to the list of callbacks. 191 * @retval OT_ERROR_ALREADY The callback was already registered. 192 * @retval OT_ERROR_NO_BUFS Could not add the callback due to resource constraints. 193 * 194 */ 195 otError otSetStateChangedCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext); 196 197 /** 198 * This function removes a callback to indicate when certain configuration or state changes within OpenThread. 199 * 200 * @param[in] aInstance A pointer to an OpenThread instance. 201 * @param[in] aCallback A pointer to a function that is called with certain configuration or state changes. 202 * @param[in] aContext A pointer to application-specific context. 203 * 204 */ 205 void otRemoveStateChangeCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext); 206 207 /** 208 * This method triggers a platform reset. 209 * 210 * The reset process ensures that all the OpenThread state/info (stored in volatile memory) is erased. Note that the 211 * `otPlatformReset` does not erase any persistent state/info saved in non-volatile memory. 212 * 213 * @param[in] aInstance A pointer to an OpenThread instance. 214 */ 215 void otInstanceReset(otInstance *aInstance); 216 217 /** 218 * This method deletes all the settings stored on non-volatile memory, and then triggers platform reset. 219 * 220 * @param[in] aInstance A pointer to an OpenThread instance. 221 */ 222 void otInstanceFactoryReset(otInstance *aInstance); 223 224 /** 225 * This function erases all the OpenThread persistent info (network settings) stored on non-volatile memory. 226 * Erase is successful only if the device is in `disabled` state/role. 227 * 228 * @param[in] aInstance A pointer to an OpenThread instance. 229 * 230 * @retval OT_ERROR_NONE All persistent info/state was erased successfully. 231 * @retval OT_ERROR_INVALID_STATE Device is not in `disabled` state/role. 232 * 233 */ 234 otError otInstanceErasePersistentInfo(otInstance *aInstance); 235 236 /** 237 * This function gets the OpenThread version string. 238 * 239 * @returns A pointer to the OpenThread version. 240 * 241 */ 242 const char *otGetVersionString(void); 243 244 /** 245 * This function gets the OpenThread radio version string. 246 * 247 * @param[in] aInstance A pointer to an OpenThread instance. 248 * 249 * @returns A pointer to the OpenThread radio version. 250 * 251 */ 252 const char *otGetRadioVersionString(otInstance *aInstance); 253 254 /** 255 * @} 256 * 257 */ 258 259 #ifdef __cplusplus 260 } // extern "C" 261 #endif 262 263 #endif // OPENTHREAD_INSTANCE_H_ 264
