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 parents. 172 * 173 * Support for this counter requires the feature option OPENTHREAD_CONFIG_MLE_INFORM_PREVIOUS_PARENT_ON_REATTACH to 174 * be enabled. 175 * 176 * A parent change can happen if device detaches from its current parent and attaches to a different one, or even 177 * while device is attached when the periodic parent search feature is enabled (please see option 178 * OPENTHREAD_CONFIG_PARENT_SEARCH_ENABLE). 179 * 180 */ 181 uint16_t mParentChanges; 182 } otMleCounters; 183 184 /** 185 * This structure represents the MLE Parent Response data. 186 * 187 */ 188 typedef struct otThreadParentResponseInfo 189 { 190 otExtAddress mExtAddr; ///< IEEE 802.15.4 Extended Address of the Parent 191 uint16_t mRloc16; ///< Short address of the Parent 192 int8_t mRssi; ///< Rssi of the Parent 193 int8_t mPriority; ///< Parent priority 194 uint8_t mLinkQuality3; ///< Parent Link Quality 3 195 uint8_t mLinkQuality2; ///< Parent Link Quality 2 196 uint8_t mLinkQuality1; ///< Parent Link Quality 1 197 bool mIsAttached; ///< Is the node receiving parent response attached 198 } otThreadParentResponseInfo; 199 200 /** 201 * This function starts Thread protocol operation. 202 * 203 * The interface must be up when calling this function. 204 * 205 * @param[in] aInstance A pointer to an OpenThread instance. 206 * @param[in] aEnabled TRUE if Thread is enabled, FALSE otherwise. 207 * 208 * @retval OT_ERROR_NONE Successfully started Thread protocol operation. 209 * @retval OT_ERROR_INVALID_STATE The network interface was not not up. 210 * 211 */ 212 otError otThreadSetEnabled(otInstance *aInstance, bool aEnabled); 213 214 /** 215 * This function gets the Thread protocol version. 216 * 217 * @returns the Thread protocol version. 218 * 219 */ 220 uint16_t otThreadGetVersion(void); 221 222 /** 223 * This function indicates whether a node is the only router on the network. 224 * 225 * @param[in] aInstance A pointer to an OpenThread instance. 226 * 227 * @retval TRUE It is the only router in the network. 228 * @retval FALSE It is a child or is not a single router in the network. 229 * 230 */ 231 bool otThreadIsSingleton(otInstance *aInstance); 232 233 /** 234 * This function starts a Thread Discovery scan. 235 * 236 * @param[in] aInstance A pointer to an OpenThread instance. 237 * @param[in] aScanChannels A bit vector indicating which channels to scan (e.g. OT_CHANNEL_11_MASK). 238 * @param[in] aPanId The PAN ID filter (set to Broadcast PAN to disable filter). 239 * @param[in] aJoiner Value of the Joiner Flag in the Discovery Request TLV. 240 * @param[in] aEnableEui64Filtering TRUE to filter responses on EUI-64, FALSE otherwise. 241 * @param[in] aCallback A pointer to a function called on receiving an MLE Discovery Response or 242 * scan completes. 243 * @param[in] aCallbackContext A pointer to application-specific context. 244 * 245 * @retval OT_ERROR_NONE Successfully started a Thread Discovery Scan. 246 * @retval OT_ERROR_INVALID_STATE The IPv6 interface is not enabled (netif is not up). 247 * @retval OT_ERROR_NO_BUFS Could not allocate message for Discovery Request. 248 * @retval OT_ERROR_BUSY Thread Discovery Scan is already in progress. 249 * 250 */ 251 otError otThreadDiscover(otInstance * aInstance, 252 uint32_t aScanChannels, 253 uint16_t aPanId, 254 bool aJoiner, 255 bool aEnableEui64Filtering, 256 otHandleActiveScanResult aCallback, 257 void * aCallbackContext); 258 259 /** 260 * This function determines if an MLE Thread Discovery is currently in progress. 261 * 262 * @param[in] aInstance A pointer to an OpenThread instance. 263 * 264 */ 265 bool otThreadIsDiscoverInProgress(otInstance *aInstance); 266 267 /** 268 * This method sets the Thread Joiner Advertisement when discovering Thread network. 269 * 270 * Thread Joiner Advertisement is used to allow a Joiner to advertise its own application-specific information 271 * (such as Vendor ID, Product ID, Discriminator, etc.) via a newly-proposed Joiner Advertisement TLV, 272 * and to make this information available to Commissioners or Commissioner Candidates without human interaction. 273 * 274 * @param[in] aInstance A pointer to an OpenThread instance. 275 * @param[in] aOui The Vendor IEEE OUI value that will be included in the Joiner Advertisement. Only the 276 * least significant 3 bytes will be used, and the most significant byte will be ignored. 277 * @param[in] aAdvData A pointer to the AdvData that will be included in the Joiner Advertisement. 278 * @param[in] aAdvDataLength The length of AdvData in bytes. 279 * 280 * @retval OT_ERROR_NONE Successfully set Joiner Advertisement. 281 * @retval OT_ERROR_INVALID_ARGS Invalid AdvData. 282 * 283 */ 284 otError otThreadSetJoinerAdvertisement(otInstance * aInstance, 285 uint32_t aOui, 286 const uint8_t *aAdvData, 287 uint8_t aAdvDataLength); 288 289 #define OT_JOINER_ADVDATA_MAX_LENGTH 64 ///< Maximum AdvData Length of Joiner Advertisement 290 291 /** 292 * Get the Thread Child Timeout used when operating in the Child role. 293 * 294 * @param[in] aInstance A pointer to an OpenThread instance. 295 * 296 * @returns The Thread Child Timeout value in seconds. 297 * 298 * @sa otThreadSetChildTimeout 299 * 300 */ 301 uint32_t otThreadGetChildTimeout(otInstance *aInstance); 302 303 /** 304 * Set the Thread Child Timeout used when operating in the Child role. 305 * 306 * @param[in] aInstance A pointer to an OpenThread instance. 307 * @param[in] aTimeout The timeout value in seconds. 308 * 309 * @sa otThreadGetChildTimeout 310 * 311 */ 312 void otThreadSetChildTimeout(otInstance *aInstance, uint32_t aTimeout); 313 314 /** 315 * Get the IEEE 802.15.4 Extended PAN ID. 316 * 317 * @param[in] aInstance A pointer to an OpenThread instance. 318 * 319 * @returns A pointer to the IEEE 802.15.4 Extended PAN ID. 320 * 321 * @sa otThreadSetExtendedPanId 322 * 323 */ 324 const otExtendedPanId *otThreadGetExtendedPanId(otInstance *aInstance); 325 326 /** 327 * Set the IEEE 802.15.4 Extended PAN ID. 328 * 329 * This function can only be called while Thread protocols are disabled. A successful 330 * call to this function invalidates the Active and Pending Operational Datasets in 331 * non-volatile memory. 332 * 333 * @param[in] aInstance A pointer to an OpenThread instance. 334 * @param[in] aExtendedPanId A pointer to the IEEE 802.15.4 Extended PAN ID. 335 * 336 * @retval OT_ERROR_NONE Successfully set the Extended PAN ID. 337 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 338 * 339 * @sa otThreadGetExtendedPanId 340 * 341 */ 342 otError otThreadSetExtendedPanId(otInstance *aInstance, const otExtendedPanId *aExtendedPanId); 343 344 /** 345 * This function returns a pointer to the Leader's RLOC. 346 * 347 * @param[in] aInstance A pointer to an OpenThread instance. 348 * @param[out] aLeaderRloc A pointer to the Leader's RLOC. 349 * 350 * @retval OT_ERROR_NONE The Leader's RLOC was successfully written to @p aLeaderRloc. 351 * @retval OT_ERROR_INVALID_ARGS @p aLeaderRloc was NULL. 352 * @retval OT_ERROR_DETACHED Not currently attached to a Thread Partition. 353 * 354 */ 355 otError otThreadGetLeaderRloc(otInstance *aInstance, otIp6Address *aLeaderRloc); 356 357 /** 358 * Get the MLE Link Mode configuration. 359 * 360 * @param[in] aInstance A pointer to an OpenThread instance. 361 * 362 * @returns The MLE Link Mode configuration. 363 * 364 * @sa otThreadSetLinkMode 365 * 366 */ 367 otLinkModeConfig otThreadGetLinkMode(otInstance *aInstance); 368 369 /** 370 * Set the MLE Link Mode configuration. 371 * 372 * @param[in] aInstance A pointer to an OpenThread instance. 373 * @param[in] aConfig A pointer to the Link Mode configuration. 374 * 375 * @retval OT_ERROR_NONE Successfully set the MLE Link Mode configuration. 376 * 377 * @sa otThreadGetLinkMode 378 * 379 */ 380 otError otThreadSetLinkMode(otInstance *aInstance, otLinkModeConfig aConfig); 381 382 /** 383 * Get the Thread Network Key. 384 * 385 * @param[in] aInstance A pointer to an OpenThread instance. 386 * 387 * @returns A pointer to a buffer containing the Thread Network Key. 388 * 389 * @sa otThreadSetNetworkKey 390 * 391 */ 392 const otNetworkKey *otThreadGetNetworkKey(otInstance *aInstance); 393 394 /** 395 * Set the Thread Network Key. 396 * 397 * This function succeeds only when Thread protocols are disabled. A successful 398 * call to this function invalidates the Active and Pending Operational Datasets in 399 * non-volatile memory. 400 * 401 * @param[in] aInstance A pointer to an OpenThread instance. 402 * @param[in] aKey A pointer to a buffer containing the Thread Network Key. 403 * 404 * @retval OT_ERROR_NONE Successfully set the Thread Network Key. 405 * @retval OT_ERROR_INVALID_ARGS If aKeyLength is larger than 16. 406 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 407 * 408 * @sa otThreadGetNetworkKey 409 * 410 */ 411 otError otThreadSetNetworkKey(otInstance *aInstance, const otNetworkKey *aKey); 412 413 /** 414 * This function returns a pointer to the Thread Routing Locator (RLOC) address. 415 * 416 * @param[in] aInstance A pointer to an OpenThread instance. 417 * 418 * @returns A pointer to the Thread Routing Locator (RLOC) address. 419 * 420 */ 421 const otIp6Address *otThreadGetRloc(otInstance *aInstance); 422 423 /** 424 * This function returns a pointer to the Mesh Local EID address. 425 * 426 * @param[in] aInstance A pointer to an OpenThread instance. 427 * 428 * @returns A pointer to the Mesh Local EID address. 429 * 430 */ 431 const otIp6Address *otThreadGetMeshLocalEid(otInstance *aInstance); 432 433 /** 434 * This function returns a pointer to the Mesh Local Prefix. 435 * 436 * @param[in] aInstance A pointer to an OpenThread instance. 437 * 438 * @returns A pointer to the Mesh Local Prefix. 439 * 440 */ 441 const otMeshLocalPrefix *otThreadGetMeshLocalPrefix(otInstance *aInstance); 442 443 /** 444 * This function sets the Mesh Local Prefix. 445 * 446 * This function succeeds only when Thread protocols are disabled. A successful 447 * call to this function invalidates the Active and Pending Operational Datasets in 448 * non-volatile memory. 449 * 450 * @param[in] aInstance A pointer to an OpenThread instance. 451 * @param[in] aMeshLocalPrefix A pointer to the Mesh Local Prefix. 452 * 453 * @retval OT_ERROR_NONE Successfully set the Mesh Local Prefix. 454 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 455 * 456 */ 457 otError otThreadSetMeshLocalPrefix(otInstance *aInstance, const otMeshLocalPrefix *aMeshLocalPrefix); 458 459 /** 460 * This function returns the Thread link-local IPv6 address. 461 * 462 * The Thread link local address is derived using IEEE802.15.4 Extended Address as Interface Identifier. 463 * 464 * @param[in] aInstance A pointer to an OpenThread instance. 465 * 466 * @returns A pointer to Thread link-local IPv6 address. 467 * 468 */ 469 const otIp6Address *otThreadGetLinkLocalIp6Address(otInstance *aInstance); 470 471 /** 472 * This function returns the Thread Link-Local All Thread Nodes multicast address. 473 * 474 * The address is a link-local Unicast Prefix-Based Multcast Address [RFC 3306], with: 475 * - flgs set to 3 (P = 1 and T = 1) 476 * - scop set to 2 477 * - plen set to 64 478 * - network prefix set to the Mesh Local Prefix 479 * - group ID set to 1 480 * 481 * @param[in] aInstance A pointer to an OpenThread instance. 482 * 483 * @returns A pointer to Thread Link-Local All Thread Nodes multicast address. 484 * 485 */ 486 const otIp6Address *otThreadGetLinkLocalAllThreadNodesMulticastAddress(otInstance *aInstance); 487 488 /** 489 * This function returns the Thread Realm-Local All Thread Nodes multicast address. 490 * 491 * The address is a realm-local Unicast Prefix-Based Multcast Address [RFC 3306], with: 492 * - flgs set to 3 (P = 1 and T = 1) 493 * - scop set to 3 494 * - plen set to 64 495 * - network prefix set to the Mesh Local Prefix 496 * - group ID set to 1 497 * 498 * @param[in] aInstance A pointer to an OpenThread instance. 499 * 500 * @returns A pointer to Thread Realm-Local All Thread Nodes multicast address. 501 * 502 */ 503 const otIp6Address *otThreadGetRealmLocalAllThreadNodesMulticastAddress(otInstance *aInstance); 504 505 /** 506 * This function retrieves the Service ALOC for given Service ID. 507 * 508 * @param[in] aInstance A pointer to an OpenThread instance. 509 * @param[in] aServiceId Service ID to get ALOC for. 510 * @param[out] aServiceAloc A pointer to output the Service ALOC. MUST NOT BE NULL. 511 * 512 * @retval OT_ERROR_NONE Successfully retrieved the Service ALOC. 513 * @retval OT_ERROR_DETACHED The Thread interface is not currently attached to a Thread Partition. 514 */ 515 otError otThreadGetServiceAloc(otInstance *aInstance, uint8_t aServiceId, otIp6Address *aServiceAloc); 516 517 /** 518 * Get the Thread Network Name. 519 * 520 * @param[in] aInstance A pointer to an OpenThread instance. 521 * 522 * @returns A pointer to the Thread Network Name. 523 * 524 * @sa otThreadSetNetworkName 525 * 526 */ 527 const char *otThreadGetNetworkName(otInstance *aInstance); 528 529 /** 530 * Set the Thread Network Name. 531 * 532 * This function succeeds only when Thread protocols are disabled. A successful 533 * call to this function invalidates the Active and Pending Operational Datasets in 534 * non-volatile memory. 535 * 536 * @param[in] aInstance A pointer to an OpenThread instance. 537 * @param[in] aNetworkName A pointer to the Thread Network Name. 538 * 539 * @retval OT_ERROR_NONE Successfully set the Thread Network Name. 540 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 541 * 542 * @sa otThreadGetNetworkName 543 * 544 */ 545 otError otThreadSetNetworkName(otInstance *aInstance, const char *aNetworkName); 546 547 /** 548 * Get the Thread Domain Name. 549 * 550 * This function is only available since Thread 1.2. 551 * 552 * @param[in] aInstance A pointer to an OpenThread instance. 553 * 554 * @returns A pointer to the Thread Domain Name. 555 * 556 * @sa otThreadSetDomainName 557 * 558 */ 559 const char *otThreadGetDomainName(otInstance *aInstance); 560 561 /** 562 * Set the Thread Domain Name. 563 * 564 * This function is only available since Thread 1.2. 565 * This function succeeds only when Thread protocols are disabled. 566 * 567 * @param[in] aInstance A pointer to an OpenThread instance. 568 * @param[in] aDomainName A pointer to the Thread Domain Name. 569 * 570 * @retval OT_ERROR_NONE Successfully set the Thread Domain Name. 571 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 572 * 573 * @sa otThreadGetDomainName 574 * 575 */ 576 otError otThreadSetDomainName(otInstance *aInstance, const char *aDomainName); 577 578 /** 579 * Set/Clear the Interface Identifier manually specified for the Thread Domain Unicast Address. 580 * 581 * This function is only available since Thread 1.2 when `OPENTHREAD_CONFIG_DUA_ENABLE` is enabled. 582 * 583 * @param[in] aInstance A pointer to an OpenThread instance. 584 * @param[in] aIid A pointer to the Interface Identifier to set or NULL to clear. 585 * 586 * @retval OT_ERROR_NONE Successfully set/cleared the Interface Identifier. 587 * @retval OT_ERROR_INVALID_ARGS The specified Interface Identifier is reserved. 588 * 589 * @sa otThreadGetFixedDuaInterfaceIdentifier 590 */ 591 otError otThreadSetFixedDuaInterfaceIdentifier(otInstance *aInstance, const otIp6InterfaceIdentifier *aIid); 592 593 /** 594 * Get the Interface Identifier manually specified for the Thread Domain Unicast Address. 595 * 596 * This function is only available since Thread 1.2 when `OPENTHREAD_CONFIG_DUA_ENABLE` is enabled. 597 * 598 * @param[in] aInstance A pointer to an OpenThread instance. 599 * 600 * @returns A pointer to the Interface Identifier which was set manually, or NULL if none was set. 601 * 602 * @sa otThreadSetFixedDuaInterfaceIdentifier 603 * 604 */ 605 const otIp6InterfaceIdentifier *otThreadGetFixedDuaInterfaceIdentifier(otInstance *aInstance); 606 607 /** 608 * Get the thrKeySequenceCounter. 609 * 610 * @param[in] aInstance A pointer to an OpenThread instance. 611 * 612 * @returns The thrKeySequenceCounter value. 613 * 614 * @sa otThreadSetKeySequenceCounter 615 * 616 */ 617 uint32_t otThreadGetKeySequenceCounter(otInstance *aInstance); 618 619 /** 620 * Set the thrKeySequenceCounter. 621 * 622 * @note This API is reserved for testing and demo purposes only. Changing settings with 623 * this API will render a production application non-compliant with the Thread Specification. 624 * 625 * @param[in] aInstance A pointer to an OpenThread instance. 626 * @param[in] aKeySequenceCounter The thrKeySequenceCounter value. 627 * 628 * @sa otThreadGetKeySequenceCounter 629 * 630 */ 631 void otThreadSetKeySequenceCounter(otInstance *aInstance, uint32_t aKeySequenceCounter); 632 633 /** 634 * Get the thrKeySwitchGuardTime 635 * 636 * @param[in] aInstance A pointer to an OpenThread instance. 637 * 638 * @returns The thrKeySwitchGuardTime value (in hours). 639 * 640 * @sa otThreadSetKeySwitchGuardTime 641 * 642 */ 643 uint32_t otThreadGetKeySwitchGuardTime(otInstance *aInstance); 644 645 /** 646 * Set the thrKeySwitchGuardTime 647 * 648 * @note This API is reserved for testing and demo purposes only. Changing settings with 649 * this API will render a production application non-compliant with the Thread Specification. 650 * 651 * @param[in] aInstance A pointer to an OpenThread instance. 652 * @param[in] aKeySwitchGuardTime The thrKeySwitchGuardTime value (in hours). 653 * 654 * @sa otThreadGetKeySwitchGuardTime 655 * 656 */ 657 void otThreadSetKeySwitchGuardTime(otInstance *aInstance, uint32_t aKeySwitchGuardTime); 658 659 /** 660 * Detach from the Thread network. 661 * 662 * @param[in] aInstance A pointer to an OpenThread instance. 663 * 664 * @retval OT_ERROR_NONE Successfully detached from the Thread network. 665 * @retval OT_ERROR_INVALID_STATE Thread is disabled. 666 * 667 */ 668 otError otThreadBecomeDetached(otInstance *aInstance); 669 670 /** 671 * Attempt to reattach as a child. 672 * 673 * @note This API is reserved for testing and demo purposes only. Changing settings with 674 * this API will render a production application non-compliant with the Thread Specification. 675 * 676 * @param[in] aInstance A pointer to an OpenThread instance. 677 * 678 * @retval OT_ERROR_NONE Successfully begin attempt to become a child. 679 * @retval OT_ERROR_INVALID_STATE Thread is disabled. 680 * 681 */ 682 otError otThreadBecomeChild(otInstance *aInstance); 683 684 /** 685 * This function gets the next neighbor information. It is used to go through the entries of 686 * the neighbor table. 687 * 688 * @param[in] aInstance A pointer to an OpenThread instance. 689 * @param[inout] aIterator A pointer to the iterator context. To get the first neighbor entry 690 it should be set to OT_NEIGHBOR_INFO_ITERATOR_INIT. 691 * @param[out] aInfo A pointer to the neighbor information. 692 * 693 * @retval OT_ERROR_NONE Successfully found the next neighbor entry in table. 694 * @retval OT_ERROR_NOT_FOUND No subsequent neighbor entry exists in the table. 695 * @retval OT_ERROR_INVALID_ARGS @p aIterator or @p aInfo was NULL. 696 * 697 */ 698 otError otThreadGetNextNeighborInfo(otInstance *aInstance, otNeighborInfoIterator *aIterator, otNeighborInfo *aInfo); 699 700 /** 701 * Get the device role. 702 * 703 * @param[in] aInstance A pointer to an OpenThread instance. 704 * 705 * @retval OT_DEVICE_ROLE_DISABLED The Thread stack is disabled. 706 * @retval OT_DEVICE_ROLE_DETACHED The device is not currently participating in a Thread network/partition. 707 * @retval OT_DEVICE_ROLE_CHILD The device is currently operating as a Thread Child. 708 * @retval OT_DEVICE_ROLE_ROUTER The device is currently operating as a Thread Router. 709 * @retval OT_DEVICE_ROLE_LEADER The device is currently operating as a Thread Leader. 710 * 711 */ 712 otDeviceRole otThreadGetDeviceRole(otInstance *aInstance); 713 714 /** 715 * Convert the device role to human-readable string. 716 * 717 * @param[in] aRole The device role to convert. 718 * 719 * @returns A string representing @p aRole. 720 * 721 */ 722 const char *otThreadDeviceRoleToString(otDeviceRole aRole); 723 724 /** 725 * This function get the Thread Leader Data. 726 * 727 * @param[in] aInstance A pointer to an OpenThread instance. 728 * @param[out] aLeaderData A pointer to where the leader data is placed. 729 * 730 * @retval OT_ERROR_NONE Successfully retrieved the leader data. 731 * @retval OT_ERROR_DETACHED Not currently attached. 732 * 733 */ 734 otError otThreadGetLeaderData(otInstance *aInstance, otLeaderData *aLeaderData); 735 736 /** 737 * Get the Leader's Router ID. 738 * 739 * @param[in] aInstance A pointer to an OpenThread instance. 740 * 741 * @returns The Leader's Router ID. 742 * 743 */ 744 uint8_t otThreadGetLeaderRouterId(otInstance *aInstance); 745 746 /** 747 * Get the Leader's Weight. 748 * 749 * @param[in] aInstance A pointer to an OpenThread instance. 750 * 751 * @returns The Leader's Weight. 752 * 753 */ 754 uint8_t otThreadGetLeaderWeight(otInstance *aInstance); 755 756 /** 757 * Get the Partition ID. 758 * 759 * @param[in] aInstance A pointer to an OpenThread instance. 760 * 761 * @returns The Partition ID. 762 * 763 */ 764 uint32_t otThreadGetPartitionId(otInstance *aInstance); 765 766 /** 767 * Get the RLOC16. 768 * 769 * @param[in] aInstance A pointer to an OpenThread instance. 770 * 771 * @returns The RLOC16. 772 * 773 */ 774 uint16_t otThreadGetRloc16(otInstance *aInstance); 775 776 /** 777 * The function retrieves diagnostic information for a Thread Router as parent. 778 * 779 * @param[in] aInstance A pointer to an OpenThread instance. 780 * @param[out] aParentInfo A pointer to where the parent router information is placed. 781 * 782 */ 783 otError otThreadGetParentInfo(otInstance *aInstance, otRouterInfo *aParentInfo); 784 785 /** 786 * The function retrieves the average RSSI for the Thread Parent. 787 * 788 * @param[in] aInstance A pointer to an OpenThread instance. 789 * @param[out] aParentRssi A pointer to where the parent RSSI should be placed. 790 * 791 */ 792 otError otThreadGetParentAverageRssi(otInstance *aInstance, int8_t *aParentRssi); 793 794 /** 795 * The function retrieves the RSSI of the last packet from the Thread Parent. 796 * 797 * @param[in] aInstance A pointer to an OpenThread instance. 798 * @param[out] aLastRssi A pointer to where the last RSSI should be placed. 799 * 800 * @retval OT_ERROR_NONE Successfully retrieved the RSSI data. 801 * @retval OT_ERROR_FAILED Unable to get RSSI data. 802 * @retval OT_ERROR_INVALID_ARGS @p aLastRssi is NULL. 803 * 804 */ 805 otError otThreadGetParentLastRssi(otInstance *aInstance, int8_t *aLastRssi); 806 807 /** 808 * Get the IPv6 counters. 809 * 810 * @param[in] aInstance A pointer to an OpenThread instance. 811 * 812 * @returns A pointer to the IPv6 counters. 813 * 814 */ 815 const otIpCounters *otThreadGetIp6Counters(otInstance *aInstance); 816 817 /** 818 * Reset the IPv6 counters. 819 * 820 * @param[in] aInstance A pointer to an OpenThread instance. 821 * 822 */ 823 void otThreadResetIp6Counters(otInstance *aInstance); 824 825 /** 826 * Get the Thread MLE counters. 827 * 828 * @param[in] aInstance A pointer to an OpenThread instance. 829 * 830 * @returns A pointer to the Thread MLE counters. 831 * 832 */ 833 const otMleCounters *otThreadGetMleCounters(otInstance *aInstance); 834 835 /** 836 * Reset the Thread MLE counters. 837 * 838 * @param[in] aInstance A pointer to an OpenThread instance. 839 * 840 */ 841 void otThreadResetMleCounters(otInstance *aInstance); 842 843 /** 844 * This function pointer is called every time an MLE Parent Response message is received. 845 * 846 * @param[in] aStats pointer to a location on stack holding the stats data. 847 * @param[in] aContext A pointer to callback client-specific context. 848 * 849 */ 850 typedef void (*otThreadParentResponseCallback)(otThreadParentResponseInfo *aInfo, void *aContext); 851 852 /** 853 * This function registers a callback to receive MLE Parent Response data. 854 * 855 * @param[in] aInstance A pointer to an OpenThread instance. 856 * @param[in] aCallback A pointer to a function that is called upon receiving an MLE Parent Response message. 857 * @param[in] aContext A pointer to callback client-specific context. 858 * 859 */ 860 void otThreadRegisterParentResponseCallback(otInstance * aInstance, 861 otThreadParentResponseCallback aCallback, 862 void * aContext); 863 864 /** 865 * This structure represents the Thread Discovery Request data. 866 * 867 */ 868 typedef struct otThreadDiscoveryRequestInfo 869 { 870 otExtAddress mExtAddress; ///< IEEE 802.15.4 Extended Address of the requester 871 uint8_t mVersion : 4; ///< Thread version. 872 bool mIsJoiner : 1; ///< Whether is from joiner. 873 } otThreadDiscoveryRequestInfo; 874 875 /** 876 * This function pointer is called every time an MLE Discovery Request message is received. 877 * 878 * @param[in] aInfo A pointer to the Discovery Request info data. 879 * @param[in] aContext A pointer to callback application-specific context. 880 * 881 */ 882 typedef void (*otThreadDiscoveryRequestCallback)(const otThreadDiscoveryRequestInfo *aInfo, void *aContext); 883 884 /** 885 * This function sets a callback to receive MLE Discovery Request data. 886 * 887 * @param[in] aInstance A pointer to an OpenThread instance. 888 * @param[in] aCallback A pointer to a function that is called upon receiving an MLE Discovery Request message. 889 * @param[in] aContext A pointer to callback application-specific context. 890 * 891 */ 892 void otThreadSetDiscoveryRequestCallback(otInstance * aInstance, 893 otThreadDiscoveryRequestCallback aCallback, 894 void * aContext); 895 896 /** 897 * This function sends a Proactive Address Notification (ADDR_NTF.ntf) message. 898 * 899 * This function is only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 900 * 901 * @param[in] aInstance A pointer to an OpenThread instance. 902 * @param[in] aDestination The destination to send the ADDR_NTF.ntf message. 903 * @param[in] aTarget The target address of the ADDR_NTF.ntf message. 904 * @param[in] aMlIid The ML-IID of the ADDR_NTF.ntf message. 905 * 906 */ 907 void otThreadSendAddressNotification(otInstance * aInstance, 908 otIp6Address * aDestination, 909 otIp6Address * aTarget, 910 otIp6InterfaceIdentifier *aMlIid); 911 912 /** 913 * This function sends a Proactive Backbone Notification (PRO_BB.ntf) message on the Backbone link. 914 * 915 * This function is only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 916 * 917 * @param[in] aInstance A pointer to an OpenThread instance. 918 * @param[in] aTarget The target address of the PRO_BB.ntf message. 919 * @param[in] aMlIid The ML-IID of the PRO_BB.ntf message. 920 * @param[in] aTimeSinceLastTransaction Time since last transaction (in seconds). 921 * 922 * @retval OT_ERROR_NONE Successfully sent PRO_BB.ntf on backbone link. 923 * @retval OT_ERROR_NO_BUFS If insufficient message buffers available. 924 * 925 */ 926 otError otThreadSendProactiveBackboneNotification(otInstance * aInstance, 927 otIp6Address * aTarget, 928 otIp6InterfaceIdentifier *aMlIid, 929 uint32_t aTimeSinceLastTransaction); 930 931 /** 932 * @} 933 * 934 */ 935 936 #ifdef __cplusplus 937 } // extern "C" 938 #endif 939 940 #endif // OPENTHREAD_THREAD_H_ 941
