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 Thread API (for both FTD and MTD). 33 */ 34 35 #ifndef OPENTHREAD_THREAD_H_ 36 #define OPENTHREAD_THREAD_H_ 37 38 #include <openthread/dataset.h> 39 #include <openthread/link.h> 40 #include <openthread/message.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @addtogroup api-thread-general 48 * 49 * @note 50 * The functions in this module require `OPENTHREAD_FTD=1` or `OPENTHREAD_MTD=1`. 51 * 52 * @{ 53 * 54 */ 55 56 /** 57 * Maximum value length of Thread Base TLV. 58 */ 59 #define OT_NETWORK_BASE_TLV_MAX_LENGTH 254 60 61 #define OT_NETWORK_MAX_ROUTER_ID 62 ///< Maximum Router ID 62 63 /** 64 * Represents a Thread device role. 65 * 66 */ 67 typedef enum 68 { 69 OT_DEVICE_ROLE_DISABLED = 0, ///< The Thread stack is disabled. 70 OT_DEVICE_ROLE_DETACHED = 1, ///< Not currently participating in a Thread network/partition. 71 OT_DEVICE_ROLE_CHILD = 2, ///< The Thread Child role. 72 OT_DEVICE_ROLE_ROUTER = 3, ///< The Thread Router role. 73 OT_DEVICE_ROLE_LEADER = 4, ///< The Thread Leader role. 74 } otDeviceRole; 75 76 /** 77 * This structure represents an MLE Link Mode configuration. 78 */ 79 typedef struct otLinkModeConfig 80 { 81 bool mRxOnWhenIdle : 1; ///< 1, if the sender has its receiver on when not transmitting. 0, otherwise. 82 bool mDeviceType : 1; ///< 1, if the sender is an FTD. 0, otherwise. 83 bool mNetworkData : 1; ///< 1, if the sender requires the full Network Data. 0, otherwise. 84 } otLinkModeConfig; 85 86 /** 87 * This structure holds diagnostic information for a neighboring Thread node 88 * 89 */ 90 typedef struct 91 { 92 otExtAddress mExtAddress; ///< IEEE 802.15.4 Extended Address 93 uint32_t mAge; ///< Time last heard 94 uint16_t mRloc16; ///< RLOC16 95 uint32_t mLinkFrameCounter; ///< Link Frame Counter 96 uint32_t mMleFrameCounter; ///< MLE Frame Counter 97 uint8_t mLinkQualityIn; ///< Link Quality In 98 int8_t mAverageRssi; ///< Average RSSI 99 int8_t mLastRssi; ///< Last observed RSSI 100 uint16_t mFrameErrorRate; ///< Frame error rate (0xffff->100%). Requires error tracking feature. 101 uint16_t mMessageErrorRate; ///< (IPv6) msg error rate (0xffff->100%). Requires error tracking feature. 102 bool mRxOnWhenIdle : 1; ///< rx-on-when-idle 103 bool mFullThreadDevice : 1; ///< Full Thread Device 104 bool mFullNetworkData : 1; ///< Full Network Data 105 bool mIsChild : 1; ///< Is the neighbor a child 106 } otNeighborInfo; 107 108 #define OT_NEIGHBOR_INFO_ITERATOR_INIT 0 ///< Initializer for otNeighborInfoIterator. 109 110 typedef int16_t otNeighborInfoIterator; ///< Used to iterate through neighbor table. 111 112 /** 113 * This structure represents the Thread Leader Data. 114 * 115 */ 116 typedef struct otLeaderData 117 { 118 uint32_t mPartitionId; ///< Partition ID 119 uint8_t mWeighting; ///< Leader Weight 120 uint8_t mDataVersion; ///< Full Network Data Version 121 uint8_t mStableDataVersion; ///< Stable Network Data Version 122 uint8_t mLeaderRouterId; ///< Leader Router ID 123 } otLeaderData; 124 125 /** 126 * This structure holds diagnostic information for a Thread Router 127 * 128 */ 129 typedef struct 130 { 131 otExtAddress mExtAddress; ///< IEEE 802.15.4 Extended Address 132 uint16_t mRloc16; ///< RLOC16 133 uint8_t mRouterId; ///< Router ID 134 uint8_t mNextHop; ///< Next hop to router 135 uint8_t mPathCost; ///< Path cost to router 136 uint8_t mLinkQualityIn; ///< Link Quality In 137 uint8_t mLinkQualityOut; ///< Link Quality Out 138 uint8_t mAge; ///< Time last heard 139 bool mAllocated : 1; ///< Router ID allocated or not 140 bool mLinkEstablished : 1; ///< Link established with Router ID or not 141 } otRouterInfo; 142 143 /** 144 * This structure represents the IP level counters. 145 * 146 */ 147 typedef struct otIpCounters 148 { 149 uint32_t mTxSuccess; ///< The number of IPv6 packets successfully transmitted. 150 uint32_t mRxSuccess; ///< The number of IPv6 packets successfully received. 151 uint32_t mTxFailure; ///< The number of IPv6 packets failed to transmit. 152 uint32_t mRxFailure; ///< The number of IPv6 packets failed to receive. 153 } otIpCounters; 154 155 /** 156 * This structure represents the Thread MLE counters. 157 * 158 */ 159 typedef struct otMleCounters 160 { 161 uint16_t mDisabledRole; ///< Number of times device entered OT_DEVICE_ROLE_DISABLED role. 162 uint16_t mDetachedRole; ///< Number of times device entered OT_DEVICE_ROLE_DETACHED role. 163 uint16_t mChildRole; ///< Number of times device entered OT_DEVICE_ROLE_CHILD role. 164 uint16_t mRouterRole; ///< Number of times device entered OT_DEVICE_ROLE_ROUTER role. 165 uint16_t mLeaderRole; ///< Number of times device entered OT_DEVICE_ROLE_LEADER role. 166 uint16_t mAttachAttempts; ///< Number of attach attempts while device was detached. 167 uint16_t mPartitionIdChanges; ///< Number of changes to partition ID. 168 uint16_t mBetterPartitionAttachAttempts; ///< Number of attempts to attach to a better partition. 169 170 /** 171 * Number of times device changed its parent. 172 * 173 * A parent change can happen if device detaches from its current parent and attaches to a different one, or even 174 * while device is attached when the periodic parent search feature is enabled (please see option 175 * OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE). 176 * 177 */ 178 uint16_t mParentChanges; 179 } otMleCounters; 180 181 /** 182 * This structure represents the MLE Parent Response data. 183 * 184 */ 185 typedef struct otThreadParentResponseInfo 186 { 187 otExtAddress mExtAddr; ///< IEEE 802.15.4 Extended Address of the Parent 188 uint16_t mRloc16; ///< Short address of the Parent 189 int8_t mRssi; ///< Rssi of the Parent 190 int8_t mPriority; ///< Parent priority 191 uint8_t mLinkQuality3; ///< Parent Link Quality 3 192 uint8_t mLinkQuality2; ///< Parent Link Quality 2 193 uint8_t mLinkQuality1; ///< Parent Link Quality 1 194 bool mIsAttached; ///< Is the node receiving parent response attached 195 } otThreadParentResponseInfo; 196 197 /** 198 * This callback informs the application that the detaching process has finished. 199 * 200 * @param[in] aContext A pointer to application-specific context. 201 * 202 */ 203 typedef void (*otDetachGracefullyCallback)(void *aContext); 204 205 /** 206 * This function starts Thread protocol operation. 207 * 208 * The interface must be up when calling this function. 209 * 210 * Calling this function with @p aEnabled set to FALSE stops any ongoing processes of detaching started by 211 * otThreadDetachGracefully(). Its callback will be called. 212 * 213 * @param[in] aInstance A pointer to an OpenThread instance. 214 * @param[in] aEnabled TRUE if Thread is enabled, FALSE otherwise. 215 * 216 * @retval OT_ERROR_NONE Successfully started Thread protocol operation. 217 * @retval OT_ERROR_INVALID_STATE The network interface was not not up. 218 * 219 */ 220 otError otThreadSetEnabled(otInstance *aInstance, bool aEnabled); 221 222 /** 223 * This function gets the Thread protocol version. 224 * 225 * @returns the Thread protocol version. 226 * 227 */ 228 uint16_t otThreadGetVersion(void); 229 230 /** 231 * This function indicates whether a node is the only router on the network. 232 * 233 * @param[in] aInstance A pointer to an OpenThread instance. 234 * 235 * @retval TRUE It is the only router in the network. 236 * @retval FALSE It is a child or is not a single router in the network. 237 * 238 */ 239 bool otThreadIsSingleton(otInstance *aInstance); 240 241 /** 242 * This function starts a Thread Discovery scan. 243 * 244 * @param[in] aInstance A pointer to an OpenThread instance. 245 * @param[in] aScanChannels A bit vector indicating which channels to scan (e.g. OT_CHANNEL_11_MASK). 246 * @param[in] aPanId The PAN ID filter (set to Broadcast PAN to disable filter). 247 * @param[in] aJoiner Value of the Joiner Flag in the Discovery Request TLV. 248 * @param[in] aEnableEui64Filtering TRUE to filter responses on EUI-64, FALSE otherwise. 249 * @param[in] aCallback A pointer to a function called on receiving an MLE Discovery Response or 250 * scan completes. 251 * @param[in] aCallbackContext A pointer to application-specific context. 252 * 253 * @retval OT_ERROR_NONE Successfully started a Thread Discovery Scan. 254 * @retval OT_ERROR_INVALID_STATE The IPv6 interface is not enabled (netif is not up). 255 * @retval OT_ERROR_NO_BUFS Could not allocate message for Discovery Request. 256 * @retval OT_ERROR_BUSY Thread Discovery Scan is already in progress. 257 * 258 */ 259 otError otThreadDiscover(otInstance * aInstance, 260 uint32_t aScanChannels, 261 uint16_t aPanId, 262 bool aJoiner, 263 bool aEnableEui64Filtering, 264 otHandleActiveScanResult aCallback, 265 void * aCallbackContext); 266 267 /** 268 * This function determines if an MLE Thread Discovery is currently in progress. 269 * 270 * @param[in] aInstance A pointer to an OpenThread instance. 271 * 272 */ 273 bool otThreadIsDiscoverInProgress(otInstance *aInstance); 274 275 /** 276 * This method sets the Thread Joiner Advertisement when discovering Thread network. 277 * 278 * Thread Joiner Advertisement is used to allow a Joiner to advertise its own application-specific information 279 * (such as Vendor ID, Product ID, Discriminator, etc.) via a newly-proposed Joiner Advertisement TLV, 280 * and to make this information available to Commissioners or Commissioner Candidates without human interaction. 281 * 282 * @param[in] aInstance A pointer to an OpenThread instance. 283 * @param[in] aOui The Vendor IEEE OUI value that will be included in the Joiner Advertisement. Only the 284 * least significant 3 bytes will be used, and the most significant byte will be ignored. 285 * @param[in] aAdvData A pointer to the AdvData that will be included in the Joiner Advertisement. 286 * @param[in] aAdvDataLength The length of AdvData in bytes. 287 * 288 * @retval OT_ERROR_NONE Successfully set Joiner Advertisement. 289 * @retval OT_ERROR_INVALID_ARGS Invalid AdvData. 290 * 291 */ 292 otError otThreadSetJoinerAdvertisement(otInstance * aInstance, 293 uint32_t aOui, 294 const uint8_t *aAdvData, 295 uint8_t aAdvDataLength); 296 297 #define OT_JOINER_ADVDATA_MAX_LENGTH 64 ///< Maximum AdvData Length of Joiner Advertisement 298 299 /** 300 * Get the Thread Child Timeout used when operating in the Child role. 301 * 302 * @param[in] aInstance A pointer to an OpenThread instance. 303 * 304 * @returns The Thread Child Timeout value in seconds. 305 * 306 * @sa otThreadSetChildTimeout 307 * 308 */ 309 uint32_t otThreadGetChildTimeout(otInstance *aInstance); 310 311 /** 312 * Set the Thread Child Timeout used when operating in the Child role. 313 * 314 * @param[in] aInstance A pointer to an OpenThread instance. 315 * @param[in] aTimeout The timeout value in seconds. 316 * 317 * @sa otThreadGetChildTimeout 318 * 319 */ 320 void otThreadSetChildTimeout(otInstance *aInstance, uint32_t aTimeout); 321 322 /** 323 * Get the IEEE 802.15.4 Extended PAN ID. 324 * 325 * @param[in] aInstance A pointer to an OpenThread instance. 326 * 327 * @returns A pointer to the IEEE 802.15.4 Extended PAN ID. 328 * 329 * @sa otThreadSetExtendedPanId 330 * 331 */ 332 const otExtendedPanId *otThreadGetExtendedPanId(otInstance *aInstance); 333 334 /** 335 * Set the IEEE 802.15.4 Extended PAN ID. 336 * 337 * This function can only be called while Thread protocols are disabled. A successful 338 * call to this function invalidates the Active and Pending Operational Datasets in 339 * non-volatile memory. 340 * 341 * @param[in] aInstance A pointer to an OpenThread instance. 342 * @param[in] aExtendedPanId A pointer to the IEEE 802.15.4 Extended PAN ID. 343 * 344 * @retval OT_ERROR_NONE Successfully set the Extended PAN ID. 345 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 346 * 347 * @sa otThreadGetExtendedPanId 348 * 349 */ 350 otError otThreadSetExtendedPanId(otInstance *aInstance, const otExtendedPanId *aExtendedPanId); 351 352 /** 353 * This function returns a pointer to the Leader's RLOC. 354 * 355 * @param[in] aInstance A pointer to an OpenThread instance. 356 * @param[out] aLeaderRloc A pointer to the Leader's RLOC. 357 * 358 * @retval OT_ERROR_NONE The Leader's RLOC was successfully written to @p aLeaderRloc. 359 * @retval OT_ERROR_INVALID_ARGS @p aLeaderRloc was NULL. 360 * @retval OT_ERROR_DETACHED Not currently attached to a Thread Partition. 361 * 362 */ 363 otError otThreadGetLeaderRloc(otInstance *aInstance, otIp6Address *aLeaderRloc); 364 365 /** 366 * Get the MLE Link Mode configuration. 367 * 368 * @param[in] aInstance A pointer to an OpenThread instance. 369 * 370 * @returns The MLE Link Mode configuration. 371 * 372 * @sa otThreadSetLinkMode 373 * 374 */ 375 otLinkModeConfig otThreadGetLinkMode(otInstance *aInstance); 376 377 /** 378 * Set the MLE Link Mode configuration. 379 * 380 * @param[in] aInstance A pointer to an OpenThread instance. 381 * @param[in] aConfig A pointer to the Link Mode configuration. 382 * 383 * @retval OT_ERROR_NONE Successfully set the MLE Link Mode configuration. 384 * 385 * @sa otThreadGetLinkMode 386 * 387 */ 388 otError otThreadSetLinkMode(otInstance *aInstance, otLinkModeConfig aConfig); 389 390 /** 391 * Get the Thread Network Key. 392 * 393 * @param[in] aInstance A pointer to an OpenThread instance. 394 * @param[out] aNetworkKey A pointer to an `otNetworkkey` to return the Thread Network Key. 395 * 396 * @sa otThreadSetNetworkKey 397 * 398 */ 399 void otThreadGetNetworkKey(otInstance *aInstance, otNetworkKey *aNetworkKey); 400 401 /** 402 * Get the `otNetworkKeyRef` for Thread Network Key. 403 * 404 * This function requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. 405 * 406 * @param[in] aInstance A pointer to an OpenThread instance. 407 * 408 * @returns Reference to the Thread Network Key stored in memory. 409 * 410 * @sa otThreadSetNetworkKeyRef 411 * 412 */ 413 otNetworkKeyRef otThreadGetNetworkKeyRef(otInstance *aInstance); 414 415 /** 416 * Set the Thread Network Key. 417 * 418 * This function succeeds only when Thread protocols are disabled. A successful 419 * call to this function invalidates the Active and Pending Operational Datasets in 420 * non-volatile memory. 421 * 422 * @param[in] aInstance A pointer to an OpenThread instance. 423 * @param[in] aKey A pointer to a buffer containing the Thread Network Key. 424 * 425 * @retval OT_ERROR_NONE Successfully set the Thread Network Key. 426 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 427 * 428 * @sa otThreadGetNetworkKey 429 * 430 */ 431 otError otThreadSetNetworkKey(otInstance *aInstance, const otNetworkKey *aKey); 432 433 /** 434 * Set the Thread Network Key as a `otNetworkKeyRef`. 435 * 436 * This function succeeds only when Thread protocols are disabled. A successful 437 * call to this function invalidates the Active and Pending Operational Datasets in 438 * non-volatile memory. 439 * 440 * This function requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. 441 * 442 * @param[in] aInstance A pointer to an OpenThread instance. 443 * @param[in] aKeyRef Reference to the Thread Network Key. 444 * 445 * @retval OT_ERROR_NONE Successfully set the Thread Network Key. 446 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 447 * 448 * @sa otThreadGetNetworkKeyRef 449 * 450 */ 451 otError otThreadSetNetworkKeyRef(otInstance *aInstance, otNetworkKeyRef aKeyRef); 452 453 /** 454 * This function returns a pointer to the Thread Routing Locator (RLOC) address. 455 * 456 * @param[in] aInstance A pointer to an OpenThread instance. 457 * 458 * @returns A pointer to the Thread Routing Locator (RLOC) address. 459 * 460 */ 461 const otIp6Address *otThreadGetRloc(otInstance *aInstance); 462 463 /** 464 * This function returns a pointer to the Mesh Local EID address. 465 * 466 * @param[in] aInstance A pointer to an OpenThread instance. 467 * 468 * @returns A pointer to the Mesh Local EID address. 469 * 470 */ 471 const otIp6Address *otThreadGetMeshLocalEid(otInstance *aInstance); 472 473 /** 474 * This function returns a pointer to the Mesh Local Prefix. 475 * 476 * @param[in] aInstance A pointer to an OpenThread instance. 477 * 478 * @returns A pointer to the Mesh Local Prefix. 479 * 480 */ 481 const otMeshLocalPrefix *otThreadGetMeshLocalPrefix(otInstance *aInstance); 482 483 /** 484 * This function sets the Mesh Local Prefix. 485 * 486 * This function succeeds only when Thread protocols are disabled. A successful 487 * call to this function invalidates the Active and Pending Operational Datasets in 488 * non-volatile memory. 489 * 490 * @param[in] aInstance A pointer to an OpenThread instance. 491 * @param[in] aMeshLocalPrefix A pointer to the Mesh Local Prefix. 492 * 493 * @retval OT_ERROR_NONE Successfully set the Mesh Local Prefix. 494 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 495 * 496 */ 497 otError otThreadSetMeshLocalPrefix(otInstance *aInstance, const otMeshLocalPrefix *aMeshLocalPrefix); 498 499 /** 500 * This function returns the Thread link-local IPv6 address. 501 * 502 * The Thread link local address is derived using IEEE802.15.4 Extended Address as Interface Identifier. 503 * 504 * @param[in] aInstance A pointer to an OpenThread instance. 505 * 506 * @returns A pointer to Thread link-local IPv6 address. 507 * 508 */ 509 const otIp6Address *otThreadGetLinkLocalIp6Address(otInstance *aInstance); 510 511 /** 512 * This function returns the Thread Link-Local All Thread Nodes multicast address. 513 * 514 * The address is a link-local Unicast Prefix-Based Multcast Address [RFC 3306], with: 515 * - flgs set to 3 (P = 1 and T = 1) 516 * - scop set to 2 517 * - plen set to 64 518 * - network prefix set to the Mesh Local Prefix 519 * - group ID set to 1 520 * 521 * @param[in] aInstance A pointer to an OpenThread instance. 522 * 523 * @returns A pointer to Thread Link-Local All Thread Nodes multicast address. 524 * 525 */ 526 const otIp6Address *otThreadGetLinkLocalAllThreadNodesMulticastAddress(otInstance *aInstance); 527 528 /** 529 * This function returns the Thread Realm-Local All Thread Nodes multicast address. 530 * 531 * The address is a realm-local Unicast Prefix-Based Multcast Address [RFC 3306], with: 532 * - flgs set to 3 (P = 1 and T = 1) 533 * - scop set to 3 534 * - plen set to 64 535 * - network prefix set to the Mesh Local Prefix 536 * - group ID set to 1 537 * 538 * @param[in] aInstance A pointer to an OpenThread instance. 539 * 540 * @returns A pointer to Thread Realm-Local All Thread Nodes multicast address. 541 * 542 */ 543 const otIp6Address *otThreadGetRealmLocalAllThreadNodesMulticastAddress(otInstance *aInstance); 544 545 /** 546 * This function retrieves the Service ALOC for given Service ID. 547 * 548 * @param[in] aInstance A pointer to an OpenThread instance. 549 * @param[in] aServiceId Service ID to get ALOC for. 550 * @param[out] aServiceAloc A pointer to output the Service ALOC. MUST NOT BE NULL. 551 * 552 * @retval OT_ERROR_NONE Successfully retrieved the Service ALOC. 553 * @retval OT_ERROR_DETACHED The Thread interface is not currently attached to a Thread Partition. 554 */ 555 otError otThreadGetServiceAloc(otInstance *aInstance, uint8_t aServiceId, otIp6Address *aServiceAloc); 556 557 /** 558 * Get the Thread Network Name. 559 * 560 * @param[in] aInstance A pointer to an OpenThread instance. 561 * 562 * @returns A pointer to the Thread Network Name. 563 * 564 * @sa otThreadSetNetworkName 565 * 566 */ 567 const char *otThreadGetNetworkName(otInstance *aInstance); 568 569 /** 570 * Set the Thread Network Name. 571 * 572 * This function succeeds only when Thread protocols are disabled. A successful 573 * call to this function invalidates the Active and Pending Operational Datasets in 574 * non-volatile memory. 575 * 576 * @param[in] aInstance A pointer to an OpenThread instance. 577 * @param[in] aNetworkName A pointer to the Thread Network Name. 578 * 579 * @retval OT_ERROR_NONE Successfully set the Thread Network Name. 580 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 581 * 582 * @sa otThreadGetNetworkName 583 * 584 */ 585 otError otThreadSetNetworkName(otInstance *aInstance, const char *aNetworkName); 586 587 /** 588 * Get the Thread Domain Name. 589 * 590 * This function is only available since Thread 1.2. 591 * 592 * @param[in] aInstance A pointer to an OpenThread instance. 593 * 594 * @returns A pointer to the Thread Domain Name. 595 * 596 * @sa otThreadSetDomainName 597 * 598 */ 599 const char *otThreadGetDomainName(otInstance *aInstance); 600 601 /** 602 * Set the Thread Domain Name. 603 * 604 * This function is only available since Thread 1.2. 605 * This function succeeds only when Thread protocols are disabled. 606 * 607 * @param[in] aInstance A pointer to an OpenThread instance. 608 * @param[in] aDomainName A pointer to the Thread Domain Name. 609 * 610 * @retval OT_ERROR_NONE Successfully set the Thread Domain Name. 611 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 612 * 613 * @sa otThreadGetDomainName 614 * 615 */ 616 otError otThreadSetDomainName(otInstance *aInstance, const char *aDomainName); 617 618 /** 619 * Set/Clear the Interface Identifier manually specified for the Thread Domain Unicast Address. 620 * 621 * This function is only available since Thread 1.2 when `OPENTHREAD_CONFIG_DUA_ENABLE` is enabled. 622 * 623 * @param[in] aInstance A pointer to an OpenThread instance. 624 * @param[in] aIid A pointer to the Interface Identifier to set or NULL to clear. 625 * 626 * @retval OT_ERROR_NONE Successfully set/cleared the Interface Identifier. 627 * @retval OT_ERROR_INVALID_ARGS The specified Interface Identifier is reserved. 628 * 629 * @sa otThreadGetFixedDuaInterfaceIdentifier 630 */ 631 otError otThreadSetFixedDuaInterfaceIdentifier(otInstance *aInstance, const otIp6InterfaceIdentifier *aIid); 632 633 /** 634 * Get the Interface Identifier manually specified for the Thread Domain Unicast Address. 635 * 636 * This function is only available since Thread 1.2 when `OPENTHREAD_CONFIG_DUA_ENABLE` is enabled. 637 * 638 * @param[in] aInstance A pointer to an OpenThread instance. 639 * 640 * @returns A pointer to the Interface Identifier which was set manually, or NULL if none was set. 641 * 642 * @sa otThreadSetFixedDuaInterfaceIdentifier 643 * 644 */ 645 const otIp6InterfaceIdentifier *otThreadGetFixedDuaInterfaceIdentifier(otInstance *aInstance); 646 647 /** 648 * Get the thrKeySequenceCounter. 649 * 650 * @param[in] aInstance A pointer to an OpenThread instance. 651 * 652 * @returns The thrKeySequenceCounter value. 653 * 654 * @sa otThreadSetKeySequenceCounter 655 * 656 */ 657 uint32_t otThreadGetKeySequenceCounter(otInstance *aInstance); 658 659 /** 660 * Set the thrKeySequenceCounter. 661 * 662 * @note This API is reserved for testing and demo purposes only. Changing settings with 663 * this API will render a production application non-compliant with the Thread Specification. 664 * 665 * @param[in] aInstance A pointer to an OpenThread instance. 666 * @param[in] aKeySequenceCounter The thrKeySequenceCounter value. 667 * 668 * @sa otThreadGetKeySequenceCounter 669 * 670 */ 671 void otThreadSetKeySequenceCounter(otInstance *aInstance, uint32_t aKeySequenceCounter); 672 673 /** 674 * Get the thrKeySwitchGuardTime 675 * 676 * @param[in] aInstance A pointer to an OpenThread instance. 677 * 678 * @returns The thrKeySwitchGuardTime value (in hours). 679 * 680 * @sa otThreadSetKeySwitchGuardTime 681 * 682 */ 683 uint32_t otThreadGetKeySwitchGuardTime(otInstance *aInstance); 684 685 /** 686 * Set the thrKeySwitchGuardTime 687 * 688 * @note This API is reserved for testing and demo purposes only. Changing settings with 689 * this API will render a production application non-compliant with the Thread Specification. 690 * 691 * @param[in] aInstance A pointer to an OpenThread instance. 692 * @param[in] aKeySwitchGuardTime The thrKeySwitchGuardTime value (in hours). 693 * 694 * @sa otThreadGetKeySwitchGuardTime 695 * 696 */ 697 void otThreadSetKeySwitchGuardTime(otInstance *aInstance, uint32_t aKeySwitchGuardTime); 698 699 /** 700 * Detach from the Thread network. 701 * 702 * @param[in] aInstance A pointer to an OpenThread instance. 703 * 704 * @retval OT_ERROR_NONE Successfully detached from the Thread network. 705 * @retval OT_ERROR_INVALID_STATE Thread is disabled. 706 * 707 */ 708 otError otThreadBecomeDetached(otInstance *aInstance); 709 710 /** 711 * Attempt to reattach as a child. 712 * 713 * @note This API is reserved for testing and demo purposes only. Changing settings with 714 * this API will render a production application non-compliant with the Thread Specification. 715 * 716 * @param[in] aInstance A pointer to an OpenThread instance. 717 * 718 * @retval OT_ERROR_NONE Successfully begin attempt to become a child. 719 * @retval OT_ERROR_INVALID_STATE Thread is disabled. 720 * 721 */ 722 otError otThreadBecomeChild(otInstance *aInstance); 723 724 /** 725 * This function gets the next neighbor information. It is used to go through the entries of 726 * the neighbor table. 727 * 728 * @param[in] aInstance A pointer to an OpenThread instance. 729 * @param[in,out] aIterator A pointer to the iterator context. To get the first neighbor entry 730 it should be set to OT_NEIGHBOR_INFO_ITERATOR_INIT. 731 * @param[out] aInfo A pointer to the neighbor information. 732 * 733 * @retval OT_ERROR_NONE Successfully found the next neighbor entry in table. 734 * @retval OT_ERROR_NOT_FOUND No subsequent neighbor entry exists in the table. 735 * @retval OT_ERROR_INVALID_ARGS @p aIterator or @p aInfo was NULL. 736 * 737 */ 738 otError otThreadGetNextNeighborInfo(otInstance *aInstance, otNeighborInfoIterator *aIterator, otNeighborInfo *aInfo); 739 740 /** 741 * Get the device role. 742 * 743 * @param[in] aInstance A pointer to an OpenThread instance. 744 * 745 * @retval OT_DEVICE_ROLE_DISABLED The Thread stack is disabled. 746 * @retval OT_DEVICE_ROLE_DETACHED The device is not currently participating in a Thread network/partition. 747 * @retval OT_DEVICE_ROLE_CHILD The device is currently operating as a Thread Child. 748 * @retval OT_DEVICE_ROLE_ROUTER The device is currently operating as a Thread Router. 749 * @retval OT_DEVICE_ROLE_LEADER The device is currently operating as a Thread Leader. 750 * 751 */ 752 otDeviceRole otThreadGetDeviceRole(otInstance *aInstance); 753 754 /** 755 * Convert the device role to human-readable string. 756 * 757 * @param[in] aRole The device role to convert. 758 * 759 * @returns A string representing @p aRole. 760 * 761 */ 762 const char *otThreadDeviceRoleToString(otDeviceRole aRole); 763 764 /** 765 * This function get the Thread Leader Data. 766 * 767 * @param[in] aInstance A pointer to an OpenThread instance. 768 * @param[out] aLeaderData A pointer to where the leader data is placed. 769 * 770 * @retval OT_ERROR_NONE Successfully retrieved the leader data. 771 * @retval OT_ERROR_DETACHED Not currently attached. 772 * 773 */ 774 otError otThreadGetLeaderData(otInstance *aInstance, otLeaderData *aLeaderData); 775 776 /** 777 * Get the Leader's Router ID. 778 * 779 * @param[in] aInstance A pointer to an OpenThread instance. 780 * 781 * @returns The Leader's Router ID. 782 * 783 */ 784 uint8_t otThreadGetLeaderRouterId(otInstance *aInstance); 785 786 /** 787 * Get the Leader's Weight. 788 * 789 * @param[in] aInstance A pointer to an OpenThread instance. 790 * 791 * @returns The Leader's Weight. 792 * 793 */ 794 uint8_t otThreadGetLeaderWeight(otInstance *aInstance); 795 796 /** 797 * Get the Partition ID. 798 * 799 * @param[in] aInstance A pointer to an OpenThread instance. 800 * 801 * @returns The Partition ID. 802 * 803 */ 804 uint32_t otThreadGetPartitionId(otInstance *aInstance); 805 806 /** 807 * Get the RLOC16. 808 * 809 * @param[in] aInstance A pointer to an OpenThread instance. 810 * 811 * @returns The RLOC16. 812 * 813 */ 814 uint16_t otThreadGetRloc16(otInstance *aInstance); 815 816 /** 817 * The function retrieves diagnostic information for a Thread Router as parent. 818 * 819 * @param[in] aInstance A pointer to an OpenThread instance. 820 * @param[out] aParentInfo A pointer to where the parent router information is placed. 821 * 822 */ 823 otError otThreadGetParentInfo(otInstance *aInstance, otRouterInfo *aParentInfo); 824 825 /** 826 * The function retrieves the average RSSI for the Thread Parent. 827 * 828 * @param[in] aInstance A pointer to an OpenThread instance. 829 * @param[out] aParentRssi A pointer to where the parent RSSI should be placed. 830 * 831 */ 832 otError otThreadGetParentAverageRssi(otInstance *aInstance, int8_t *aParentRssi); 833 834 /** 835 * The function retrieves the RSSI of the last packet from the Thread Parent. 836 * 837 * @param[in] aInstance A pointer to an OpenThread instance. 838 * @param[out] aLastRssi A pointer to where the last RSSI should be placed. 839 * 840 * @retval OT_ERROR_NONE Successfully retrieved the RSSI data. 841 * @retval OT_ERROR_FAILED Unable to get RSSI data. 842 * @retval OT_ERROR_INVALID_ARGS @p aLastRssi is NULL. 843 * 844 */ 845 otError otThreadGetParentLastRssi(otInstance *aInstance, int8_t *aLastRssi); 846 847 /** 848 * Get the IPv6 counters. 849 * 850 * @param[in] aInstance A pointer to an OpenThread instance. 851 * 852 * @returns A pointer to the IPv6 counters. 853 * 854 */ 855 const otIpCounters *otThreadGetIp6Counters(otInstance *aInstance); 856 857 /** 858 * Reset the IPv6 counters. 859 * 860 * @param[in] aInstance A pointer to an OpenThread instance. 861 * 862 */ 863 void otThreadResetIp6Counters(otInstance *aInstance); 864 865 /** 866 * Get the Thread MLE counters. 867 * 868 * @param[in] aInstance A pointer to an OpenThread instance. 869 * 870 * @returns A pointer to the Thread MLE counters. 871 * 872 */ 873 const otMleCounters *otThreadGetMleCounters(otInstance *aInstance); 874 875 /** 876 * Reset the Thread MLE counters. 877 * 878 * @param[in] aInstance A pointer to an OpenThread instance. 879 * 880 */ 881 void otThreadResetMleCounters(otInstance *aInstance); 882 883 /** 884 * This function pointer is called every time an MLE Parent Response message is received. 885 * 886 * @param[in] aInfo A pointer to a location on stack holding the stats data. 887 * @param[in] aContext A pointer to callback client-specific context. 888 * 889 */ 890 typedef void (*otThreadParentResponseCallback)(otThreadParentResponseInfo *aInfo, void *aContext); 891 892 /** 893 * This function registers a callback to receive MLE Parent Response data. 894 * 895 * @param[in] aInstance A pointer to an OpenThread instance. 896 * @param[in] aCallback A pointer to a function that is called upon receiving an MLE Parent Response message. 897 * @param[in] aContext A pointer to callback client-specific context. 898 * 899 */ 900 void otThreadRegisterParentResponseCallback(otInstance * aInstance, 901 otThreadParentResponseCallback aCallback, 902 void * aContext); 903 904 /** 905 * This structure represents the Thread Discovery Request data. 906 * 907 */ 908 typedef struct otThreadDiscoveryRequestInfo 909 { 910 otExtAddress mExtAddress; ///< IEEE 802.15.4 Extended Address of the requester 911 uint8_t mVersion : 4; ///< Thread version. 912 bool mIsJoiner : 1; ///< Whether is from joiner. 913 } otThreadDiscoveryRequestInfo; 914 915 /** 916 * This function pointer is called every time an MLE Discovery Request message is received. 917 * 918 * @param[in] aInfo A pointer to the Discovery Request info data. 919 * @param[in] aContext A pointer to callback application-specific context. 920 * 921 */ 922 typedef void (*otThreadDiscoveryRequestCallback)(const otThreadDiscoveryRequestInfo *aInfo, void *aContext); 923 924 /** 925 * This function sets a callback to receive MLE Discovery Request data. 926 * 927 * @param[in] aInstance A pointer to an OpenThread instance. 928 * @param[in] aCallback A pointer to a function that is called upon receiving an MLE Discovery Request message. 929 * @param[in] aContext A pointer to callback application-specific context. 930 * 931 */ 932 void otThreadSetDiscoveryRequestCallback(otInstance * aInstance, 933 otThreadDiscoveryRequestCallback aCallback, 934 void * aContext); 935 936 /** 937 * This function pointer type defines the callback to notify the outcome of a `otThreadLocateAnycastDestination()` 938 * request. 939 * 940 * @param[in] aContext A pointer to an arbitrary context (provided when callback is registered). 941 * @param[in] aError The error when handling the request. OT_ERROR_NONE indicates success. 942 * OT_ERROR_RESPONSE_TIMEOUT indicates a destination could not be found. 943 * OT_ERROR_ABORT indicates the request was aborted. 944 * @param[in] aMeshLocalAddress A pointer to the mesh-local EID of the closest destination of the anycast address 945 * when @p aError is OT_ERROR_NONE, NULL otherwise. 946 * @param[in] aRloc16 The RLOC16 of the destination if found, otherwise invalid RLOC16 (0xfffe). 947 * 948 */ 949 typedef void (*otThreadAnycastLocatorCallback)(void * aContext, 950 otError aError, 951 const otIp6Address *aMeshLocalAddress, 952 uint16_t aRloc16); 953 954 /** 955 * This function requests the closest destination of a given anycast address to be located. 956 * 957 * This function is only available when `OPENTHREAD_CONFIG_TMF_ANYCAST_LOCATOR_ENABLE` is enabled. 958 * 959 * If a previous request is ongoing, a subsequent call to this function will cancel and replace the earlier request. 960 * 961 * @param[in] aInstance A pointer to an OpenThread instance. 962 * @param[in] aAnycastAddress The anycast address to locate. MUST NOT be NULL. 963 * @param[in] aCallback The callback function to report the result. 964 * @param[in] aContext An arbitrary context used with @p aCallback. 965 * 966 * @retval OT_ERROR_NONE The request started successfully. @p aCallback will be invoked to report the result. 967 * @retval OT_ERROR_INVALID_ARGS The @p aAnycastAddress is not a valid anycast address or @p aCallback is NULL. 968 * @retval OT_ERROR_NO_BUFS Out of buffer to prepare and send the request message. 969 * 970 */ 971 otError otThreadLocateAnycastDestination(otInstance * aInstance, 972 const otIp6Address * aAnycastAddress, 973 otThreadAnycastLocatorCallback aCallback, 974 void * aContext); 975 976 /** 977 * This function indicates whether an anycast locate request is currently in progress. 978 * 979 * This function is only available when `OPENTHREAD_CONFIG_TMF_ANYCAST_LOCATOR_ENABLE` is enabled. 980 * 981 * @param[in] aInstance A pointer to an OpenThread instance. 982 * 983 * @returns TRUE if an anycast locate request is currently in progress, FALSE otherwise. 984 * 985 */ 986 bool otThreadIsAnycastLocateInProgress(otInstance *aInstance); 987 988 /** 989 * This function sends a Proactive Address Notification (ADDR_NTF.ntf) message. 990 * 991 * This function is only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 992 * 993 * @param[in] aInstance A pointer to an OpenThread instance. 994 * @param[in] aDestination The destination to send the ADDR_NTF.ntf message. 995 * @param[in] aTarget The target address of the ADDR_NTF.ntf message. 996 * @param[in] aMlIid The ML-IID of the ADDR_NTF.ntf message. 997 * 998 */ 999 void otThreadSendAddressNotification(otInstance * aInstance, 1000 otIp6Address * aDestination, 1001 otIp6Address * aTarget, 1002 otIp6InterfaceIdentifier *aMlIid); 1003 1004 /** 1005 * This function sends a Proactive Backbone Notification (PRO_BB.ntf) message on the Backbone link. 1006 * 1007 * This function is only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 1008 * 1009 * @param[in] aInstance A pointer to an OpenThread instance. 1010 * @param[in] aTarget The target address of the PRO_BB.ntf message. 1011 * @param[in] aMlIid The ML-IID of the PRO_BB.ntf message. 1012 * @param[in] aTimeSinceLastTransaction Time since last transaction (in seconds). 1013 * 1014 * @retval OT_ERROR_NONE Successfully sent PRO_BB.ntf on backbone link. 1015 * @retval OT_ERROR_NO_BUFS If insufficient message buffers available. 1016 * 1017 */ 1018 otError otThreadSendProactiveBackboneNotification(otInstance * aInstance, 1019 otIp6Address * aTarget, 1020 otIp6InterfaceIdentifier *aMlIid, 1021 uint32_t aTimeSinceLastTransaction); 1022 1023 /** 1024 * This function notifies other nodes in the network (if any) and then stops Thread protocol operation. 1025 * 1026 * It sends an Address Release if it's a router, or sets its child timeout to 0 if it's a child. 1027 * 1028 * @param[in] aInstance A pointer to an OpenThread instance. 1029 * @param[in] aCallback A pointer to a function that is called upon finishing detaching. 1030 * @param[in] aContext A pointer to callback application-specific context. 1031 * 1032 * @retval OT_ERROR_NONE Successfully started detaching. 1033 * @retval OT_ERROR_BUSY Detaching is already in progress. 1034 * 1035 */ 1036 otError otThreadDetachGracefully(otInstance *aInstance, otDetachGracefullyCallback aCallback, void *aContext); 1037 1038 /** 1039 * @} 1040 * 1041 */ 1042 1043 #ifdef __cplusplus 1044 } // extern "C" 1045 #endif 1046 1047 #endif // OPENTHREAD_THREAD_H_ 1048