1 /* 2 * Copyright (c) 2016-2017, 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 (FTD only). 33 */ 34 35 #ifndef OPENTHREAD_THREAD_FTD_H_ 36 #define OPENTHREAD_THREAD_FTD_H_ 37 38 #include <openthread/link.h> 39 #include <openthread/message.h> 40 #include <openthread/thread.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @addtogroup api-thread-router 48 * 49 * @{ 50 * 51 */ 52 53 /** 54 * Holds diagnostic information for a Thread Child 55 * 56 */ 57 typedef struct 58 { 59 otExtAddress mExtAddress; ///< IEEE 802.15.4 Extended Address 60 uint32_t mTimeout; ///< Timeout 61 uint32_t mAge; ///< Seconds since last heard 62 uint64_t mConnectionTime; ///< Seconds since attach (requires `OPENTHREAD_CONFIG_UPTIME_ENABLE`) 63 uint16_t mRloc16; ///< RLOC16 64 uint16_t mChildId; ///< Child ID 65 uint8_t mNetworkDataVersion; ///< Network Data Version 66 uint8_t mLinkQualityIn; ///< Link Quality In 67 int8_t mAverageRssi; ///< Average RSSI 68 int8_t mLastRssi; ///< Last observed RSSI 69 uint16_t mFrameErrorRate; ///< Frame error rate (0xffff->100%). Requires error tracking feature. 70 uint16_t mMessageErrorRate; ///< (IPv6) msg error rate (0xffff->100%). Requires error tracking feature. 71 uint16_t mQueuedMessageCnt; ///< Number of queued messages for the child. 72 uint16_t mSupervisionInterval; ///< Supervision interval (in seconds). 73 uint8_t mVersion; ///< MLE version 74 bool mRxOnWhenIdle : 1; ///< rx-on-when-idle 75 bool mFullThreadDevice : 1; ///< Full Thread Device 76 bool mFullNetworkData : 1; ///< Full Network Data 77 bool mIsStateRestoring : 1; ///< Is in restoring state 78 bool mIsCslSynced : 1; ///< Is child CSL synchronized 79 } otChildInfo; 80 81 #define OT_CHILD_IP6_ADDRESS_ITERATOR_INIT 0 ///< Initializer for otChildIP6AddressIterator 82 83 typedef uint16_t otChildIp6AddressIterator; ///< Used to iterate through IPv6 addresses of a Thread Child entry. 84 85 /** 86 * Defines the EID cache entry state. 87 * 88 */ 89 typedef enum otCacheEntryState 90 { 91 OT_CACHE_ENTRY_STATE_CACHED = 0, // Entry is cached and in-use. 92 OT_CACHE_ENTRY_STATE_SNOOPED = 1, // Entry is created by snoop optimization (inspection of received msg). 93 OT_CACHE_ENTRY_STATE_QUERY = 2, // Entry represents an ongoing query for the EID. 94 OT_CACHE_ENTRY_STATE_RETRY_QUERY = 3, // Entry is in retry wait mode (a prior query did not get a response). 95 } otCacheEntryState; 96 97 /** 98 * Represents an EID cache entry. 99 * 100 */ 101 typedef struct otCacheEntryInfo 102 { 103 otIp6Address mTarget; ///< Target EID 104 otShortAddress mRloc16; ///< RLOC16 105 otCacheEntryState mState; ///< Entry state 106 bool mCanEvict : 1; ///< Indicates whether the entry can be evicted. 107 bool mRampDown : 1; ///< Whether in ramp-down mode while in `OT_CACHE_ENTRY_STATE_RETRY_QUERY`. 108 bool mValidLastTrans : 1; ///< Indicates whether last transaction time and ML-EID are valid. 109 uint32_t mLastTransTime; ///< Last transaction time (applicable in cached state). 110 otIp6Address mMeshLocalEid; ///< Mesh Local EID (applicable if entry in cached state). 111 uint16_t mTimeout; ///< Timeout in seconds (applicable if in snooped/query/retry-query states). 112 uint16_t mRetryDelay; ///< Retry delay in seconds (applicable if in query-retry state). 113 } otCacheEntryInfo; 114 115 /** 116 * Represents an iterator used for iterating through the EID cache table entries. 117 * 118 * To initialize the iterator and start from the first entry in the cache table, set all its fields in the structure to 119 * zero (e.g., `memset` the iterator to zero). 120 * 121 */ 122 typedef struct otCacheEntryIterator 123 { 124 const void *mData[2]; ///< Opaque data used by the core implementation. Should not be changed by user. 125 } otCacheEntryIterator; 126 127 /** 128 * Gets the maximum number of children currently allowed. 129 * 130 * @param[in] aInstance A pointer to an OpenThread instance. 131 * 132 * @returns The maximum number of children currently allowed. 133 * 134 * @sa otThreadSetMaxAllowedChildren 135 * 136 */ 137 uint16_t otThreadGetMaxAllowedChildren(otInstance *aInstance); 138 139 /** 140 * Sets the maximum number of children currently allowed. 141 * 142 * This parameter can only be set when Thread protocol operation has been stopped. 143 * 144 * @param[in] aInstance A pointer to an OpenThread instance. 145 * @param[in] aMaxChildren The maximum allowed children. 146 * 147 * @retval OT_ERROR_NONE Successfully set the max. 148 * @retval OT_ERROR_INVALID_ARGS If @p aMaxChildren is not in the range [1, OPENTHREAD_CONFIG_MLE_MAX_CHILDREN]. 149 * @retval OT_ERROR_INVALID_STATE If Thread isn't stopped. 150 * 151 * @sa otThreadGetMaxAllowedChildren 152 * 153 */ 154 otError otThreadSetMaxAllowedChildren(otInstance *aInstance, uint16_t aMaxChildren); 155 156 /** 157 * Indicates whether or not the device is router-eligible. 158 * 159 * @param[in] aInstance A pointer to an OpenThread instance. 160 * 161 * @retval TRUE If device is router-eligible. 162 * @retval FALSE If device is not router-eligible. 163 * 164 */ 165 bool otThreadIsRouterEligible(otInstance *aInstance); 166 167 /** 168 * Sets whether or not the device is router-eligible. 169 * 170 * If @p aEligible is false and the device is currently operating as a router, this call will cause the device to 171 * detach and attempt to reattach as a child. 172 * 173 * @param[in] aInstance A pointer to an OpenThread instance. 174 * @param[in] aEligible TRUE to configure the device as router-eligible, FALSE otherwise. 175 * 176 * @retval OT_ERROR_NONE Successfully set the router-eligible configuration. 177 * @retval OT_ERROR_NOT_CAPABLE The device is not capable of becoming a router. 178 * 179 */ 180 otError otThreadSetRouterEligible(otInstance *aInstance, bool aEligible); 181 182 /** 183 * Set the preferred Router Id. 184 * 185 * Upon becoming a router/leader the node attempts to use this Router Id. If the preferred Router Id is not set or if 186 * it can not be used, a randomly generated router id is picked. This property can be set only when the device role is 187 * either detached or disabled. 188 * 189 * @note This API is reserved for testing and demo purposes only. Changing settings with 190 * this API will render a production application non-compliant with the Thread Specification. 191 * 192 * @param[in] aInstance A pointer to an OpenThread instance. 193 * @param[in] aRouterId The preferred Router Id. 194 * 195 * @retval OT_ERROR_NONE Successfully set the preferred Router Id. 196 * @retval OT_ERROR_INVALID_STATE Could not set (role is not detached or disabled) 197 * 198 */ 199 otError otThreadSetPreferredRouterId(otInstance *aInstance, uint8_t aRouterId); 200 201 /** 202 * Represents the power supply property on a device. 203 * 204 * This is used as a property in `otDeviceProperties` to calculate the leader weight. 205 * 206 */ 207 typedef enum 208 { 209 OT_POWER_SUPPLY_BATTERY = 0, ///< Battery powered. 210 OT_POWER_SUPPLY_EXTERNAL = 1, ///< Externally powered (mains-powered). 211 OT_POWER_SUPPLY_EXTERNAL_STABLE = 2, ///< Stable external power with a battery backup or UPS. 212 OT_POWER_SUPPLY_EXTERNAL_UNSTABLE = 3, ///< Potentially unstable ext power (e.g. light bulb powered via a switch). 213 } otPowerSupply; 214 215 /** 216 * Represents the device properties which are used for calculating the local leader weight on a 217 * device. 218 * 219 * The parameters are set based on device's capability, whether acting as border router, its power supply config, etc. 220 * 221 * `mIsUnstable` indicates operational stability of device and is determined via a vendor specific mechanism. It can 222 * include the following cases: 223 * - Device internally detects that it loses external power supply more often than usual. What is usual is 224 * determined by the vendor. 225 * - Device internally detects that it reboots more often than usual. What is usual is determined by the vendor. 226 * 227 */ 228 typedef struct otDeviceProperties 229 { 230 otPowerSupply mPowerSupply; ///< Power supply config. 231 bool mIsBorderRouter : 1; ///< Whether device is a border router. 232 bool mSupportsCcm : 1; ///< Whether device supports CCM (can act as a CCM border router). 233 bool mIsUnstable : 1; ///< Operational stability of device (vendor specific). 234 int8_t mLeaderWeightAdjustment; ///< Weight adjustment. Should be -16 to +16 (clamped otherwise). 235 } otDeviceProperties; 236 237 /** 238 * Get the current device properties. 239 * 240 * Requires `OPENTHREAD_CONFIG_MLE_DEVICE_PROPERTY_LEADER_WEIGHT_ENABLE`. 241 * 242 * @returns The device properties `otDeviceProperties`. 243 * 244 */ 245 const otDeviceProperties *otThreadGetDeviceProperties(otInstance *aInstance); 246 247 /** 248 * Set the device properties which are then used to determine and set the Leader Weight. 249 * 250 * Requires `OPENTHREAD_CONFIG_MLE_DEVICE_PROPERTY_LEADER_WEIGHT_ENABLE`. 251 * 252 * @param[in] aInstance A pointer to an OpenThread instance. 253 * @param[in] aDeviceProperties The device properties. 254 * 255 */ 256 void otThreadSetDeviceProperties(otInstance *aInstance, const otDeviceProperties *aDeviceProperties); 257 258 /** 259 * Gets the Thread Leader Weight used when operating in the Leader role. 260 * 261 * @param[in] aInstance A pointer to an OpenThread instance. 262 * 263 * @returns The Thread Leader Weight value. 264 * 265 * @sa otThreadSetLeaderWeight 266 * @sa otThreadSetDeviceProperties 267 * 268 */ 269 uint8_t otThreadGetLocalLeaderWeight(otInstance *aInstance); 270 271 /** 272 * Sets the Thread Leader Weight used when operating in the Leader role. 273 * 274 * Directly sets the Leader Weight to the new value, replacing its previous value (which may have been 275 * determined from the current `otDeviceProperties`). 276 * 277 * @param[in] aInstance A pointer to an OpenThread instance. 278 * @param[in] aWeight The Thread Leader Weight value. 279 * 280 * @sa otThreadGetLeaderWeight 281 * 282 */ 283 void otThreadSetLocalLeaderWeight(otInstance *aInstance, uint8_t aWeight); 284 285 /** 286 * Get the preferred Thread Leader Partition Id used when operating in the Leader role. 287 * 288 * @param[in] aInstance A pointer to an OpenThread instance. 289 * 290 * @returns The Thread Leader Partition Id value. 291 * 292 */ 293 uint32_t otThreadGetPreferredLeaderPartitionId(otInstance *aInstance); 294 295 /** 296 * Set the preferred Thread Leader Partition Id used when operating in the Leader role. 297 * 298 * @param[in] aInstance A pointer to an OpenThread instance. 299 * @param[in] aPartitionId The Thread Leader Partition Id value. 300 * 301 */ 302 void otThreadSetPreferredLeaderPartitionId(otInstance *aInstance, uint32_t aPartitionId); 303 304 /** 305 * Gets the Joiner UDP Port. 306 * 307 * @param[in] aInstance A pointer to an OpenThread instance. 308 * 309 * @returns The Joiner UDP Port number. 310 * 311 * @sa otThreadSetJoinerUdpPort 312 * 313 */ 314 uint16_t otThreadGetJoinerUdpPort(otInstance *aInstance); 315 316 /** 317 * Sets the Joiner UDP Port. 318 * 319 * @param[in] aInstance A pointer to an OpenThread instance. 320 * @param[in] aJoinerUdpPort The Joiner UDP Port number. 321 * 322 * @retval OT_ERROR_NONE Successfully set the Joiner UDP Port. 323 * 324 * @sa otThreadGetJoinerUdpPort 325 * 326 */ 327 otError otThreadSetJoinerUdpPort(otInstance *aInstance, uint16_t aJoinerUdpPort); 328 329 /** 330 * Set Steering data out of band. 331 * 332 * Configuration option `OPENTHREAD_CONFIG_MLE_STEERING_DATA_SET_OOB_ENABLE` should be set to enable setting of steering 333 * data out of band. 334 * 335 * @param[in] aInstance A pointer to an OpenThread instance. 336 * @param[in] aExtAddress Address used to update the steering data. 337 * All zeros to clear the steering data (no steering data). 338 * All 0xFFs to set steering data/bloom filter to accept/allow all. 339 * A specific EUI64 which is then added to current steering data/bloom filter. 340 * 341 */ 342 void otThreadSetSteeringData(otInstance *aInstance, const otExtAddress *aExtAddress); 343 344 /** 345 * Get the CONTEXT_ID_REUSE_DELAY parameter used in the Leader role. 346 * 347 * @param[in] aInstance A pointer to an OpenThread instance. 348 * 349 * @returns The CONTEXT_ID_REUSE_DELAY value. 350 * 351 * @sa otThreadSetContextIdReuseDelay 352 * 353 */ 354 uint32_t otThreadGetContextIdReuseDelay(otInstance *aInstance); 355 356 /** 357 * Set the CONTEXT_ID_REUSE_DELAY parameter used in the Leader role. 358 * 359 * @note This API is reserved for testing and demo purposes only. Changing settings with 360 * this API will render a production application non-compliant with the Thread Specification. 361 * 362 * @param[in] aInstance A pointer to an OpenThread instance. 363 * @param[in] aDelay The CONTEXT_ID_REUSE_DELAY value. 364 * 365 * @sa otThreadGetContextIdReuseDelay 366 * 367 */ 368 void otThreadSetContextIdReuseDelay(otInstance *aInstance, uint32_t aDelay); 369 370 /** 371 * Get the `NETWORK_ID_TIMEOUT` parameter. 372 * 373 * @note This API is reserved for testing and demo purposes only. Changing settings with 374 * this API will render a production application non-compliant with the Thread Specification. 375 * 376 * @param[in] aInstance A pointer to an OpenThread instance. 377 * 378 * @returns The `NETWORK_ID_TIMEOUT` value. 379 * 380 * @sa otThreadSetNetworkIdTimeout 381 * 382 */ 383 uint8_t otThreadGetNetworkIdTimeout(otInstance *aInstance); 384 385 /** 386 * Set the `NETWORK_ID_TIMEOUT` parameter. 387 * 388 * @note This API is reserved for testing and demo purposes only. Changing settings with 389 * this API will render a production application non-compliant with the Thread Specification. 390 * 391 * @param[in] aInstance A pointer to an OpenThread instance. 392 * @param[in] aTimeout The `NETWORK_ID_TIMEOUT` value. 393 * 394 * @sa otThreadGetNetworkIdTimeout 395 * 396 */ 397 void otThreadSetNetworkIdTimeout(otInstance *aInstance, uint8_t aTimeout); 398 399 /** 400 * Get the ROUTER_UPGRADE_THRESHOLD parameter used in the REED role. 401 * 402 * @param[in] aInstance A pointer to an OpenThread instance. 403 * 404 * @returns The ROUTER_UPGRADE_THRESHOLD value. 405 * 406 * @sa otThreadSetRouterUpgradeThreshold 407 * 408 */ 409 uint8_t otThreadGetRouterUpgradeThreshold(otInstance *aInstance); 410 411 /** 412 * Set the ROUTER_UPGRADE_THRESHOLD parameter used in the Leader role. 413 * 414 * @note This API is reserved for testing and demo purposes only. Changing settings with 415 * this API will render a production application non-compliant with the Thread Specification. 416 * 417 * @param[in] aInstance A pointer to an OpenThread instance. 418 * @param[in] aThreshold The ROUTER_UPGRADE_THRESHOLD value. 419 * 420 * @sa otThreadGetRouterUpgradeThreshold 421 * 422 */ 423 void otThreadSetRouterUpgradeThreshold(otInstance *aInstance, uint8_t aThreshold); 424 425 /** 426 * Get the MLE_CHILD_ROUTER_LINKS parameter used in the REED role. 427 * 428 * This parameter specifies the max number of neighboring routers with which the device (as an FED) 429 * will try to establish link. 430 * 431 * @param[in] aInstance A pointer to an OpenThread instance. 432 * 433 * @returns The MLE_CHILD_ROUTER_LINKS value. 434 * 435 * @sa otThreadSetChildRouterLinks 436 * 437 */ 438 uint8_t otThreadGetChildRouterLinks(otInstance *aInstance); 439 440 /** 441 * Set the MLE_CHILD_ROUTER_LINKS parameter used in the REED role. 442 * 443 * @param[in] aInstance A pointer to an OpenThread instance. 444 * @param[in] aChildRouterLinks The MLE_CHILD_ROUTER_LINKS value. 445 * 446 * @retval OT_ERROR_NONE Successfully set the value. 447 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 448 * 449 * @sa otThreadGetChildRouterLinks 450 * 451 */ 452 otError otThreadSetChildRouterLinks(otInstance *aInstance, uint8_t aChildRouterLinks); 453 454 /** 455 * Release a Router ID that has been allocated by the device in the Leader role. 456 * 457 * @note This API is reserved for testing and demo purposes only. Changing settings with 458 * this API will render a production application non-compliant with the Thread Specification. 459 * 460 * @param[in] aInstance A pointer to an OpenThread instance. 461 * @param[in] aRouterId The Router ID to release. Valid range is [0, 62]. 462 * 463 * @retval OT_ERROR_NONE Successfully released the router id. 464 * @retval OT_ERROR_INVALID_ARGS @p aRouterId is not in the range [0, 62]. 465 * @retval OT_ERROR_INVALID_STATE The device is not currently operating as a leader. 466 * @retval OT_ERROR_NOT_FOUND The router id is not currently allocated. 467 * 468 */ 469 otError otThreadReleaseRouterId(otInstance *aInstance, uint8_t aRouterId); 470 471 /** 472 * Attempt to become a router. 473 * 474 * @note This API is reserved for testing and demo purposes only. Changing settings with 475 * this API will render a production application non-compliant with the Thread Specification. 476 * 477 * @param[in] aInstance A pointer to an OpenThread instance. 478 * 479 * @retval OT_ERROR_NONE Successfully begin attempt to become a router. 480 * @retval OT_ERROR_INVALID_STATE Thread is disabled. 481 */ 482 otError otThreadBecomeRouter(otInstance *aInstance); 483 484 /** 485 * Become a leader and start a new partition. 486 * 487 * @note This API is reserved for testing and demo purposes only. Changing settings with 488 * this API will render a production application non-compliant with the Thread Specification. 489 * 490 * @param[in] aInstance A pointer to an OpenThread instance. 491 * 492 * @retval OT_ERROR_NONE Successfully became a leader and started a new partition. 493 * @retval OT_ERROR_INVALID_STATE Thread is disabled. 494 */ 495 otError otThreadBecomeLeader(otInstance *aInstance); 496 497 /** 498 * Get the ROUTER_DOWNGRADE_THRESHOLD parameter used in the Router role. 499 * 500 * @param[in] aInstance A pointer to an OpenThread instance. 501 * 502 * @returns The ROUTER_DOWNGRADE_THRESHOLD value. 503 * 504 * @sa otThreadSetRouterDowngradeThreshold 505 * 506 */ 507 uint8_t otThreadGetRouterDowngradeThreshold(otInstance *aInstance); 508 509 /** 510 * Set the ROUTER_DOWNGRADE_THRESHOLD parameter used in the Leader role. 511 * 512 * @note This API is reserved for testing and demo purposes only. Changing settings with 513 * this API will render a production application non-compliant with the Thread Specification. 514 * 515 * @param[in] aInstance A pointer to an OpenThread instance. 516 * @param[in] aThreshold The ROUTER_DOWNGRADE_THRESHOLD value. 517 * 518 * @sa otThreadGetRouterDowngradeThreshold 519 * 520 */ 521 void otThreadSetRouterDowngradeThreshold(otInstance *aInstance, uint8_t aThreshold); 522 523 /** 524 * Get the ROUTER_SELECTION_JITTER parameter used in the REED/Router role. 525 * 526 * @param[in] aInstance A pointer to an OpenThread instance. 527 * 528 * @returns The ROUTER_SELECTION_JITTER value. 529 * 530 * @sa otThreadSetRouterSelectionJitter 531 * 532 */ 533 uint8_t otThreadGetRouterSelectionJitter(otInstance *aInstance); 534 535 /** 536 * Set the ROUTER_SELECTION_JITTER parameter used in the REED/Router role. 537 * 538 * @note This API is reserved for testing and demo purposes only. Changing settings with 539 * this API will render a production application non-compliant with the Thread Specification. 540 * 541 * @param[in] aInstance A pointer to an OpenThread instance. 542 * @param[in] aRouterJitter The ROUTER_SELECTION_JITTER value. 543 * 544 * @sa otThreadGetRouterSelectionJitter 545 * 546 */ 547 void otThreadSetRouterSelectionJitter(otInstance *aInstance, uint8_t aRouterJitter); 548 549 /** 550 * Gets diagnostic information for an attached Child by its Child ID or RLOC16. 551 * 552 * @param[in] aInstance A pointer to an OpenThread instance. 553 * @param[in] aChildId The Child ID or RLOC16 for the attached child. 554 * @param[out] aChildInfo A pointer to where the child information is placed. 555 * 556 * @retval OT_ERROR_NONE @p aChildInfo was successfully updated with the info for the given ID. 557 * @retval OT_ERROR_NOT_FOUND No valid child with this Child ID. 558 * @retval OT_ERROR_INVALID_ARGS If @p aChildInfo is NULL. 559 * 560 */ 561 otError otThreadGetChildInfoById(otInstance *aInstance, uint16_t aChildId, otChildInfo *aChildInfo); 562 563 /** 564 * The function retains diagnostic information for an attached Child by the internal table index. 565 * 566 * @param[in] aInstance A pointer to an OpenThread instance. 567 * @param[in] aChildIndex The table index. 568 * @param[out] aChildInfo A pointer to where the child information is placed. 569 * 570 * @retval OT_ERROR_NONE @p aChildInfo was successfully updated with the info for the given index. 571 * @retval OT_ERROR_NOT_FOUND No valid child at this index. 572 * @retval OT_ERROR_INVALID_ARGS Either @p aChildInfo is NULL, or @p aChildIndex is out of range (higher 573 * than max table index). 574 * 575 * @sa otGetMaxAllowedChildren 576 * 577 */ 578 otError otThreadGetChildInfoByIndex(otInstance *aInstance, uint16_t aChildIndex, otChildInfo *aChildInfo); 579 580 /** 581 * Gets the next IPv6 address (using an iterator) for a given child. 582 * 583 * @param[in] aInstance A pointer to an OpenThread instance. 584 * @param[in] aChildIndex The child index. 585 * @param[in,out] aIterator A pointer to the iterator. On success the iterator will be updated to point to next 586 * entry in the list. To get the first IPv6 address the iterator should be set to 587 * OT_CHILD_IP6_ADDRESS_ITERATOR_INIT. 588 * @param[out] aAddress A pointer to an IPv6 address where the child's next address is placed (on success). 589 * 590 * @retval OT_ERROR_NONE Successfully found the next IPv6 address (@p aAddress was successfully updated). 591 * @retval OT_ERROR_NOT_FOUND The child has no subsequent IPv6 address entry. 592 * @retval OT_ERROR_INVALID_ARGS @p aIterator or @p aAddress are NULL, or child at @p aChildIndex is not valid. 593 * 594 * @sa otThreadGetChildInfoByIndex 595 * 596 */ 597 otError otThreadGetChildNextIp6Address(otInstance *aInstance, 598 uint16_t aChildIndex, 599 otChildIp6AddressIterator *aIterator, 600 otIp6Address *aAddress); 601 602 /** 603 * Get the current Router ID Sequence. 604 * 605 * @param[in] aInstance A pointer to an OpenThread instance. 606 * 607 * @returns The Router ID Sequence. 608 * 609 */ 610 uint8_t otThreadGetRouterIdSequence(otInstance *aInstance); 611 612 /** 613 * The function returns the maximum allowed router ID 614 * 615 * @param[in] aInstance A pointer to an OpenThread instance. 616 * 617 * @returns The maximum allowed router ID. 618 * 619 */ 620 uint8_t otThreadGetMaxRouterId(otInstance *aInstance); 621 622 /** 623 * The function retains diagnostic information for a given Thread Router. 624 * 625 * @param[in] aInstance A pointer to an OpenThread instance. 626 * @param[in] aRouterId The router ID or RLOC16 for a given router. 627 * @param[out] aRouterInfo A pointer to where the router information is placed. 628 * 629 * @retval OT_ERROR_NONE Successfully retrieved the router info for given id. 630 * @retval OT_ERROR_NOT_FOUND No router entry with the given id. 631 * @retval OT_ERROR_INVALID_ARGS @p aRouterInfo is NULL. 632 * 633 */ 634 otError otThreadGetRouterInfo(otInstance *aInstance, uint16_t aRouterId, otRouterInfo *aRouterInfo); 635 636 /** 637 * Gets the next EID cache entry (using an iterator). 638 * 639 * @param[in] aInstance A pointer to an OpenThread instance. 640 * @param[out] aEntryInfo A pointer to where the EID cache entry information is placed. 641 * @param[in,out] aIterator A pointer to an iterator. It will be updated to point to next entry on success. To get 642 * the first entry, initialize the iterator by setting all its fields to zero 643 * (e.g., `memset` the iterator structure to zero). 644 * 645 * @retval OT_ERROR_NONE Successfully populated @p aEntryInfo for next EID cache entry. 646 * @retval OT_ERROR_NOT_FOUND No more entries in the address cache table. 647 * 648 */ 649 otError otThreadGetNextCacheEntry(otInstance *aInstance, otCacheEntryInfo *aEntryInfo, otCacheEntryIterator *aIterator); 650 651 /** 652 * Get the Thread PSKc 653 * 654 * @param[in] aInstance A pointer to an OpenThread instance. 655 * @param[out] aPskc A pointer to an `otPskc` to return the retrieved Thread PSKc. 656 * 657 * @sa otThreadSetPskc 658 * 659 */ 660 void otThreadGetPskc(otInstance *aInstance, otPskc *aPskc); 661 662 /** 663 * Get Key Reference to Thread PSKc stored 664 * 665 * Requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. 666 * 667 * @param[in] aInstance A pointer to an OpenThread instance. 668 * 669 * @returns Key Reference to PSKc 670 * 671 * @sa otThreadSetPskcRef 672 * 673 */ 674 otPskcRef otThreadGetPskcRef(otInstance *aInstance); 675 676 /** 677 * Set the Thread PSKc 678 * 679 * Will only succeed when Thread protocols are disabled. A successful 680 * call to this function will also invalidate the Active and Pending Operational Datasets in 681 * non-volatile memory. 682 * 683 * @param[in] aInstance A pointer to an OpenThread instance. 684 * @param[in] aPskc A pointer to the new Thread PSKc. 685 * 686 * @retval OT_ERROR_NONE Successfully set the Thread PSKc. 687 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 688 * 689 * @sa otThreadGetPskc 690 * 691 */ 692 otError otThreadSetPskc(otInstance *aInstance, const otPskc *aPskc); 693 694 /** 695 * Set the Key Reference to the Thread PSKc 696 * 697 * Requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. 698 * 699 * Will only succeed when Thread protocols are disabled. Upon success, 700 * this will also invalidate the Active and Pending Operational Datasets in 701 * non-volatile memory. 702 * 703 * @param[in] aInstance A pointer to an OpenThread instance. 704 * @param[in] aKeyRef Key Reference to the new Thread PSKc. 705 * 706 * @retval OT_ERROR_NONE Successfully set the Thread PSKc. 707 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 708 * 709 * @sa otThreadGetPskcRef 710 * 711 */ 712 otError otThreadSetPskcRef(otInstance *aInstance, otPskcRef aKeyRef); 713 714 /** 715 * Get the assigned parent priority. 716 * 717 * @param[in] aInstance A pointer to an OpenThread instance. 718 * 719 * @returns The assigned parent priority value, -2 means not assigned. 720 * 721 * @sa otThreadSetParentPriority 722 * 723 */ 724 int8_t otThreadGetParentPriority(otInstance *aInstance); 725 726 /** 727 * Set the parent priority. 728 * 729 * @note This API is reserved for testing and demo purposes only. Changing settings with 730 * this API will render a production application non-compliant with the Thread Specification. 731 * 732 * @param[in] aInstance A pointer to an OpenThread instance. 733 * @param[in] aParentPriority The parent priority value. 734 * 735 * @retval OT_ERROR_NONE Successfully set the parent priority. 736 * @retval OT_ERROR_INVALID_ARGS If the parent priority value is not among 1, 0, -1 and -2. 737 * 738 * @sa otThreadGetParentPriority 739 * 740 */ 741 otError otThreadSetParentPriority(otInstance *aInstance, int8_t aParentPriority); 742 743 /** 744 * Gets the maximum number of IP addresses that each MTD child may register with this device as parent. 745 * 746 * @param[in] aInstance A pointer to an OpenThread instance. 747 * 748 * @returns The maximum number of IP addresses that each MTD child may register with this device as parent. 749 * 750 * @sa otThreadSetMaxChildIpAddresses 751 * 752 */ 753 uint8_t otThreadGetMaxChildIpAddresses(otInstance *aInstance); 754 755 /** 756 * Sets or restores the maximum number of IP addresses that each MTD child may register with this 757 * device as parent. 758 * 759 * Pass `0` to clear the setting and restore the default. 760 * 761 * Available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 762 * 763 * @note Only used by Thread Test Harness to limit the address registrations of the reference 764 * parent in order to test the MTD DUT reaction. 765 * 766 * @param[in] aInstance A pointer to an OpenThread instance. 767 * @param[in] aMaxIpAddresses The maximum number of IP addresses that each MTD child may register with this 768 * device as parent. 0 to clear the setting and restore the default. 769 * 770 * @retval OT_ERROR_NONE Successfully set/cleared the number. 771 * @retval OT_ERROR_INVALID_ARGS If exceeds the allowed maximum number. 772 * 773 * @sa otThreadGetMaxChildIpAddresses 774 * 775 */ 776 otError otThreadSetMaxChildIpAddresses(otInstance *aInstance, uint8_t aMaxIpAddresses); 777 778 /** 779 * Defines the constants used in `otNeighborTableCallback` to indicate changes in neighbor table. 780 * 781 */ 782 typedef enum 783 { 784 OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED, ///< A child is being added. 785 OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED, ///< A child is being removed. 786 OT_NEIGHBOR_TABLE_EVENT_CHILD_MODE_CHANGED, ///< An existing child's mode is changed. 787 OT_NEIGHBOR_TABLE_EVENT_ROUTER_ADDED, ///< A router is being added. 788 OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED, ///< A router is being removed. 789 } otNeighborTableEvent; 790 791 /** 792 * Represent a neighbor table entry info (child or router) and is used as a parameter in the neighbor table 793 * callback `otNeighborTableCallback`. 794 * 795 */ 796 typedef struct 797 { 798 otInstance *mInstance; ///< The OpenThread instance. 799 union 800 { 801 otChildInfo mChild; ///< The child neighbor info. 802 otNeighborInfo mRouter; ///< The router neighbor info. 803 } mInfo; 804 } otNeighborTableEntryInfo; 805 806 /** 807 * Pointer is called to notify that there is a change in the neighbor table. 808 * 809 * @param[in] aEvent A event flag. 810 * @param[in] aEntryInfo A pointer to table entry info. 811 * 812 */ 813 typedef void (*otNeighborTableCallback)(otNeighborTableEvent aEvent, const otNeighborTableEntryInfo *aEntryInfo); 814 815 /** 816 * Registers a neighbor table callback function. 817 * 818 * The provided callback (if non-NULL) will be invoked when there is a change in the neighbor table (e.g., a child or a 819 * router neighbor entry is being added/removed or an existing child's mode is changed). 820 * 821 * Subsequent calls to this method will overwrite the previous callback. Note that this callback in invoked while the 822 * neighbor/child table is being updated and always before the `otStateChangedCallback`. 823 * 824 * @param[in] aInstance A pointer to an OpenThread instance. 825 * @param[in] aCallback A pointer to callback handler function. 826 * 827 */ 828 void otThreadRegisterNeighborTableCallback(otInstance *aInstance, otNeighborTableCallback aCallback); 829 830 /** 831 * Sets whether the device was commissioned using CCM. 832 * 833 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used by Thread Test Harness 834 * to indicate whether this device was commissioned using CCM. 835 * 836 * @param[in] aInstance A pointer to an OpenThread instance. 837 * @param[in] aEnabled TRUE if the device was commissioned using CCM, FALSE otherwise. 838 * 839 */ 840 void otThreadSetCcmEnabled(otInstance *aInstance, bool aEnabled); 841 842 /** 843 * Sets whether the Security Policy TLV version-threshold for routing (VR field) is enabled. 844 * 845 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used by Thread Test Harness 846 * to indicate that thread protocol version check VR should be skipped. 847 * 848 * @param[in] aInstance A pointer to an OpenThread instance. 849 * @param[in] aEnabled TRUE to enable Security Policy TLV version-threshold for routing, FALSE otherwise. 850 * 851 */ 852 void otThreadSetThreadVersionCheckEnabled(otInstance *aInstance, bool aEnabled); 853 854 /** 855 * Gets the range of router IDs that are allowed to assign to nodes within the thread network. 856 * 857 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used for test purpose. All the 858 * router IDs in the range [aMinRouterId, aMaxRouterId] are allowed. 859 * 860 * @param[in] aInstance A pointer to an OpenThread instance. 861 * @param[out] aMinRouterId The minimum router ID. 862 * @param[out] aMaxRouterId The maximum router ID. 863 * 864 * @sa otThreadSetRouterIdRange 865 * 866 */ 867 void otThreadGetRouterIdRange(otInstance *aInstance, uint8_t *aMinRouterId, uint8_t *aMaxRouterId); 868 869 /** 870 * Sets the range of router IDs that are allowed to assign to nodes within the thread network. 871 * 872 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used for test purpose. All the 873 * router IDs in the range [aMinRouterId, aMaxRouterId] are allowed. 874 * 875 * @param[in] aInstance A pointer to an OpenThread instance. 876 * @param[in] aMinRouterId The minimum router ID. 877 * @param[in] aMaxRouterId The maximum router ID. 878 * 879 * @retval OT_ERROR_NONE Successfully set the range. 880 * @retval OT_ERROR_INVALID_ARGS aMinRouterId > aMaxRouterId, or the range is not covered by [0, 62]. 881 * 882 * @sa otThreadGetRouterIdRange 883 * 884 */ 885 otError otThreadSetRouterIdRange(otInstance *aInstance, uint8_t aMinRouterId, uint8_t aMaxRouterId); 886 887 /** 888 * Gets the current Interval Max value used by Advertisement trickle timer. 889 * 890 * This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is intended for testing only. 891 * 892 * @returns The Interval Max of Advertisement trickle timer in milliseconds. 893 * 894 */ 895 uint32_t otThreadGetAdvertisementTrickleIntervalMax(otInstance *aInstance); 896 897 /** 898 * Indicates whether or not a Router ID is currently allocated. 899 * 900 * @param[in] aInstance A pointer to an OpenThread instance. 901 * @param[in] aRouterId The router ID to check. 902 * 903 * @retval TRUE The @p aRouterId is allocated. 904 * @retval FALSE The @p aRouterId is not allocated. 905 * 906 */ 907 bool otThreadIsRouterIdAllocated(otInstance *aInstance, uint8_t aRouterId); 908 909 /** 910 * Gets the next hop and path cost towards a given RLOC16 destination. 911 * 912 * Can be used with either @p aNextHopRloc16 or @p aPathCost being NULL indicating caller does not want 913 * to get the value. 914 * 915 * @param[in] aInstance A pointer to an OpenThread instance. 916 * @param[in] aDestRloc16 The RLOC16 of destination. 917 * @param[out] aNextHopRloc16 A pointer to return RLOC16 of next hop, 0xfffe if no next hop. 918 * @param[out] aPathCost A pointer to return path cost towards destination. 919 * 920 */ 921 void otThreadGetNextHopAndPathCost(otInstance *aInstance, 922 uint16_t aDestRloc16, 923 uint16_t *aNextHopRloc16, 924 uint8_t *aPathCost); 925 926 /** 927 * @} 928 * 929 */ 930 931 #ifdef __cplusplus 932 } // extern "C" 933 #endif 934 935 #endif // OPENTHREAD_THREAD_FTD_H_ 936
