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