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