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 used in the Router role. 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 used in the Leader role. 387 * 388 * @param[in] aInstance A pointer to an OpenThread instance. 389 * @param[in] aTimeout The NETWORK_ID_TIMEOUT value. 390 * 391 * @sa otThreadGetNetworkIdTimeout 392 * 393 */ 394 void otThreadSetNetworkIdTimeout(otInstance *aInstance, uint8_t aTimeout); 395 396 /** 397 * Get the ROUTER_UPGRADE_THRESHOLD parameter used in the REED role. 398 * 399 * @param[in] aInstance A pointer to an OpenThread instance. 400 * 401 * @returns The ROUTER_UPGRADE_THRESHOLD value. 402 * 403 * @sa otThreadSetRouterUpgradeThreshold 404 * 405 */ 406 uint8_t otThreadGetRouterUpgradeThreshold(otInstance *aInstance); 407 408 /** 409 * Set the ROUTER_UPGRADE_THRESHOLD parameter used in the Leader role. 410 * 411 * @note This API is reserved for testing and demo purposes only. Changing settings with 412 * this API will render a production application non-compliant with the Thread Specification. 413 * 414 * @param[in] aInstance A pointer to an OpenThread instance. 415 * @param[in] aThreshold The ROUTER_UPGRADE_THRESHOLD value. 416 * 417 * @sa otThreadGetRouterUpgradeThreshold 418 * 419 */ 420 void otThreadSetRouterUpgradeThreshold(otInstance *aInstance, uint8_t aThreshold); 421 422 /** 423 * Get the MLE_CHILD_ROUTER_LINKS parameter used in the REED role. 424 * 425 * This parameter specifies the max number of neighboring routers with which the device (as an FED) 426 * will try to establish link. 427 * 428 * @param[in] aInstance A pointer to an OpenThread instance. 429 * 430 * @returns The MLE_CHILD_ROUTER_LINKS value. 431 * 432 * @sa otThreadSetChildRouterLinks 433 * 434 */ 435 uint8_t otThreadGetChildRouterLinks(otInstance *aInstance); 436 437 /** 438 * Set the MLE_CHILD_ROUTER_LINKS parameter used in the REED role. 439 * 440 * @param[in] aInstance A pointer to an OpenThread instance. 441 * @param[in] aChildRouterLinks The MLE_CHILD_ROUTER_LINKS value. 442 * 443 * @retval OT_ERROR_NONE Successfully set the value. 444 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 445 * 446 * @sa otThreadGetChildRouterLinks 447 * 448 */ 449 otError otThreadSetChildRouterLinks(otInstance *aInstance, uint8_t aChildRouterLinks); 450 451 /** 452 * Release a Router ID that has been allocated by the device in the Leader role. 453 * 454 * @note This API is reserved for testing and demo purposes only. Changing settings with 455 * this API will render a production application non-compliant with the Thread Specification. 456 * 457 * @param[in] aInstance A pointer to an OpenThread instance. 458 * @param[in] aRouterId The Router ID to release. Valid range is [0, 62]. 459 * 460 * @retval OT_ERROR_NONE Successfully released the router id. 461 * @retval OT_ERROR_INVALID_ARGS @p aRouterId is not in the range [0, 62]. 462 * @retval OT_ERROR_INVALID_STATE The device is not currently operating as a leader. 463 * @retval OT_ERROR_NOT_FOUND The router id is not currently allocated. 464 * 465 */ 466 otError otThreadReleaseRouterId(otInstance *aInstance, uint8_t aRouterId); 467 468 /** 469 * Attempt to become a router. 470 * 471 * @note This API is reserved for testing and demo purposes only. Changing settings with 472 * this API will render a production application non-compliant with the Thread Specification. 473 * 474 * @param[in] aInstance A pointer to an OpenThread instance. 475 * 476 * @retval OT_ERROR_NONE Successfully begin attempt to become a router. 477 * @retval OT_ERROR_INVALID_STATE Thread is disabled. 478 */ 479 otError otThreadBecomeRouter(otInstance *aInstance); 480 481 /** 482 * Become a leader and start a new partition. 483 * 484 * @note This API is reserved for testing and demo purposes only. Changing settings with 485 * this API will render a production application non-compliant with the Thread Specification. 486 * 487 * @param[in] aInstance A pointer to an OpenThread instance. 488 * 489 * @retval OT_ERROR_NONE Successfully became a leader and started a new partition. 490 * @retval OT_ERROR_INVALID_STATE Thread is disabled. 491 */ 492 otError otThreadBecomeLeader(otInstance *aInstance); 493 494 /** 495 * Get the ROUTER_DOWNGRADE_THRESHOLD parameter used in the Router role. 496 * 497 * @param[in] aInstance A pointer to an OpenThread instance. 498 * 499 * @returns The ROUTER_DOWNGRADE_THRESHOLD value. 500 * 501 * @sa otThreadSetRouterDowngradeThreshold 502 * 503 */ 504 uint8_t otThreadGetRouterDowngradeThreshold(otInstance *aInstance); 505 506 /** 507 * Set the ROUTER_DOWNGRADE_THRESHOLD parameter used in the Leader role. 508 * 509 * @note This API is reserved for testing and demo purposes only. Changing settings with 510 * this API will render a production application non-compliant with the Thread Specification. 511 * 512 * @param[in] aInstance A pointer to an OpenThread instance. 513 * @param[in] aThreshold The ROUTER_DOWNGRADE_THRESHOLD value. 514 * 515 * @sa otThreadGetRouterDowngradeThreshold 516 * 517 */ 518 void otThreadSetRouterDowngradeThreshold(otInstance *aInstance, uint8_t aThreshold); 519 520 /** 521 * Get the ROUTER_SELECTION_JITTER parameter used in the REED/Router role. 522 * 523 * @param[in] aInstance A pointer to an OpenThread instance. 524 * 525 * @returns The ROUTER_SELECTION_JITTER value. 526 * 527 * @sa otThreadSetRouterSelectionJitter 528 * 529 */ 530 uint8_t otThreadGetRouterSelectionJitter(otInstance *aInstance); 531 532 /** 533 * Set the ROUTER_SELECTION_JITTER parameter used in the REED/Router role. 534 * 535 * @note This API is reserved for testing and demo purposes only. Changing settings with 536 * this API will render a production application non-compliant with the Thread Specification. 537 * 538 * @param[in] aInstance A pointer to an OpenThread instance. 539 * @param[in] aRouterJitter The ROUTER_SELECTION_JITTER value. 540 * 541 * @sa otThreadGetRouterSelectionJitter 542 * 543 */ 544 void otThreadSetRouterSelectionJitter(otInstance *aInstance, uint8_t aRouterJitter); 545 546 /** 547 * Gets diagnostic information for an attached Child by its Child ID or RLOC16. 548 * 549 * @param[in] aInstance A pointer to an OpenThread instance. 550 * @param[in] aChildId The Child ID or RLOC16 for the attached child. 551 * @param[out] aChildInfo A pointer to where the child information is placed. 552 * 553 * @retval OT_ERROR_NONE @p aChildInfo was successfully updated with the info for the given ID. 554 * @retval OT_ERROR_NOT_FOUND No valid child with this Child ID. 555 * @retval OT_ERROR_INVALID_ARGS If @p aChildInfo is NULL. 556 * 557 */ 558 otError otThreadGetChildInfoById(otInstance *aInstance, uint16_t aChildId, otChildInfo *aChildInfo); 559 560 /** 561 * The function retains diagnostic information for an attached Child by the internal table index. 562 * 563 * @param[in] aInstance A pointer to an OpenThread instance. 564 * @param[in] aChildIndex The table index. 565 * @param[out] aChildInfo A pointer to where the child information is placed. 566 * 567 * @retval OT_ERROR_NONE @p aChildInfo was successfully updated with the info for the given index. 568 * @retval OT_ERROR_NOT_FOUND No valid child at this index. 569 * @retval OT_ERROR_INVALID_ARGS Either @p aChildInfo is NULL, or @p aChildIndex is out of range (higher 570 * than max table index). 571 * 572 * @sa otGetMaxAllowedChildren 573 * 574 */ 575 otError otThreadGetChildInfoByIndex(otInstance *aInstance, uint16_t aChildIndex, otChildInfo *aChildInfo); 576 577 /** 578 * Gets the next IPv6 address (using an iterator) for a given child. 579 * 580 * @param[in] aInstance A pointer to an OpenThread instance. 581 * @param[in] aChildIndex The child index. 582 * @param[in,out] aIterator A pointer to the iterator. On success the iterator will be updated to point to next 583 * entry in the list. To get the first IPv6 address the iterator should be set to 584 * OT_CHILD_IP6_ADDRESS_ITERATOR_INIT. 585 * @param[out] aAddress A pointer to an IPv6 address where the child's next address is placed (on success). 586 * 587 * @retval OT_ERROR_NONE Successfully found the next IPv6 address (@p aAddress was successfully updated). 588 * @retval OT_ERROR_NOT_FOUND The child has no subsequent IPv6 address entry. 589 * @retval OT_ERROR_INVALID_ARGS @p aIterator or @p aAddress are NULL, or child at @p aChildIndex is not valid. 590 * 591 * @sa otThreadGetChildInfoByIndex 592 * 593 */ 594 otError otThreadGetChildNextIp6Address(otInstance *aInstance, 595 uint16_t aChildIndex, 596 otChildIp6AddressIterator *aIterator, 597 otIp6Address *aAddress); 598 599 /** 600 * Get the current Router ID Sequence. 601 * 602 * @param[in] aInstance A pointer to an OpenThread instance. 603 * 604 * @returns The Router ID Sequence. 605 * 606 */ 607 uint8_t otThreadGetRouterIdSequence(otInstance *aInstance); 608 609 /** 610 * The function returns the maximum allowed router ID 611 * 612 * @param[in] aInstance A pointer to an OpenThread instance. 613 * 614 * @returns The maximum allowed router ID. 615 * 616 */ 617 uint8_t otThreadGetMaxRouterId(otInstance *aInstance); 618 619 /** 620 * The function retains diagnostic information for a given Thread Router. 621 * 622 * @param[in] aInstance A pointer to an OpenThread instance. 623 * @param[in] aRouterId The router ID or RLOC16 for a given router. 624 * @param[out] aRouterInfo A pointer to where the router information is placed. 625 * 626 * @retval OT_ERROR_NONE Successfully retrieved the router info for given id. 627 * @retval OT_ERROR_NOT_FOUND No router entry with the given id. 628 * @retval OT_ERROR_INVALID_ARGS @p aRouterInfo is NULL. 629 * 630 */ 631 otError otThreadGetRouterInfo(otInstance *aInstance, uint16_t aRouterId, otRouterInfo *aRouterInfo); 632 633 /** 634 * Gets the next EID cache entry (using an iterator). 635 * 636 * @param[in] aInstance A pointer to an OpenThread instance. 637 * @param[out] aEntryInfo A pointer to where the EID cache entry information is placed. 638 * @param[in,out] aIterator A pointer to an iterator. It will be updated to point to next entry on success. To get 639 * the first entry, initialize the iterator by setting all its fields to zero 640 * (e.g., `memset` the iterator structure to zero). 641 * 642 * @retval OT_ERROR_NONE Successfully populated @p aEntryInfo for next EID cache entry. 643 * @retval OT_ERROR_NOT_FOUND No more entries in the address cache table. 644 * 645 */ 646 otError otThreadGetNextCacheEntry(otInstance *aInstance, otCacheEntryInfo *aEntryInfo, otCacheEntryIterator *aIterator); 647 648 /** 649 * Get the Thread PSKc 650 * 651 * @param[in] aInstance A pointer to an OpenThread instance. 652 * @param[out] aPskc A pointer to an `otPskc` to return the retrieved Thread PSKc. 653 * 654 * @sa otThreadSetPskc 655 * 656 */ 657 void otThreadGetPskc(otInstance *aInstance, otPskc *aPskc); 658 659 /** 660 * Get Key Reference to Thread PSKc stored 661 * 662 * Requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. 663 * 664 * @param[in] aInstance A pointer to an OpenThread instance. 665 * 666 * @returns Key Reference to PSKc 667 * 668 * @sa otThreadSetPskcRef 669 * 670 */ 671 otPskcRef otThreadGetPskcRef(otInstance *aInstance); 672 673 /** 674 * Set the Thread PSKc 675 * 676 * Will only succeed when Thread protocols are disabled. A successful 677 * call to this function will also invalidate the Active and Pending Operational Datasets in 678 * non-volatile memory. 679 * 680 * @param[in] aInstance A pointer to an OpenThread instance. 681 * @param[in] aPskc A pointer to the new Thread PSKc. 682 * 683 * @retval OT_ERROR_NONE Successfully set the Thread PSKc. 684 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 685 * 686 * @sa otThreadGetPskc 687 * 688 */ 689 otError otThreadSetPskc(otInstance *aInstance, const otPskc *aPskc); 690 691 /** 692 * Set the Key Reference to the Thread PSKc 693 * 694 * Requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. 695 * 696 * Will only succeed when Thread protocols are disabled. Upon success, 697 * this will also invalidate the Active and Pending Operational Datasets in 698 * non-volatile memory. 699 * 700 * @param[in] aInstance A pointer to an OpenThread instance. 701 * @param[in] aKeyRef Key Reference to the new Thread PSKc. 702 * 703 * @retval OT_ERROR_NONE Successfully set the Thread PSKc. 704 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 705 * 706 * @sa otThreadGetPskcRef 707 * 708 */ 709 otError otThreadSetPskcRef(otInstance *aInstance, otPskcRef aKeyRef); 710 711 /** 712 * Get the assigned parent priority. 713 * 714 * @param[in] aInstance A pointer to an OpenThread instance. 715 * 716 * @returns The assigned parent priority value, -2 means not assigned. 717 * 718 * @sa otThreadSetParentPriority 719 * 720 */ 721 int8_t otThreadGetParentPriority(otInstance *aInstance); 722 723 /** 724 * Set the parent priority. 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] aParentPriority The parent priority value. 731 * 732 * @retval OT_ERROR_NONE Successfully set the parent priority. 733 * @retval OT_ERROR_INVALID_ARGS If the parent priority value is not among 1, 0, -1 and -2. 734 * 735 * @sa otThreadGetParentPriority 736 * 737 */ 738 otError otThreadSetParentPriority(otInstance *aInstance, int8_t aParentPriority); 739 740 /** 741 * Gets the maximum number of IP addresses that each MTD child may register with this device as parent. 742 * 743 * @param[in] aInstance A pointer to an OpenThread instance. 744 * 745 * @returns The maximum number of IP addresses that each MTD child may register with this device as parent. 746 * 747 * @sa otThreadSetMaxChildIpAddresses 748 * 749 */ 750 uint8_t otThreadGetMaxChildIpAddresses(otInstance *aInstance); 751 752 /** 753 * Sets or restores the maximum number of IP addresses that each MTD child may register with this 754 * device as parent. 755 * 756 * Pass `0` to clear the setting and restore the default. 757 * 758 * Available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 759 * 760 * @note Only used by Thread Test Harness to limit the address registrations of the reference 761 * parent in order to test the MTD DUT reaction. 762 * 763 * @param[in] aInstance A pointer to an OpenThread instance. 764 * @param[in] aMaxIpAddresses The maximum number of IP addresses that each MTD child may register with this 765 * device as parent. 0 to clear the setting and restore the default. 766 * 767 * @retval OT_ERROR_NONE Successfully set/cleared the number. 768 * @retval OT_ERROR_INVALID_ARGS If exceeds the allowed maximum number. 769 * 770 * @sa otThreadGetMaxChildIpAddresses 771 * 772 */ 773 otError otThreadSetMaxChildIpAddresses(otInstance *aInstance, uint8_t aMaxIpAddresses); 774 775 /** 776 * Defines the constants used in `otNeighborTableCallback` to indicate changes in neighbor table. 777 * 778 */ 779 typedef enum 780 { 781 OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED, ///< A child is being added. 782 OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED, ///< A child is being removed. 783 OT_NEIGHBOR_TABLE_EVENT_CHILD_MODE_CHANGED, ///< An existing child's mode is changed. 784 OT_NEIGHBOR_TABLE_EVENT_ROUTER_ADDED, ///< A router is being added. 785 OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED, ///< A router is being removed. 786 } otNeighborTableEvent; 787 788 /** 789 * Represent a neighbor table entry info (child or router) and is used as a parameter in the neighbor table 790 * callback `otNeighborTableCallback`. 791 * 792 */ 793 typedef struct 794 { 795 otInstance *mInstance; ///< The OpenThread instance. 796 union 797 { 798 otChildInfo mChild; ///< The child neighbor info. 799 otNeighborInfo mRouter; ///< The router neighbor info. 800 } mInfo; 801 } otNeighborTableEntryInfo; 802 803 /** 804 * Pointer is called to notify that there is a change in the neighbor table. 805 * 806 * @param[in] aEvent A event flag. 807 * @param[in] aEntryInfo A pointer to table entry info. 808 * 809 */ 810 typedef void (*otNeighborTableCallback)(otNeighborTableEvent aEvent, const otNeighborTableEntryInfo *aEntryInfo); 811 812 /** 813 * Registers a neighbor table callback function. 814 * 815 * The provided callback (if non-NULL) will be invoked when there is a change in the neighbor table (e.g., a child or a 816 * router neighbor entry is being added/removed or an existing child's mode is changed). 817 * 818 * Subsequent calls to this method will overwrite the previous callback. Note that this callback in invoked while the 819 * neighbor/child table is being updated and always before the `otStateChangedCallback`. 820 * 821 * @param[in] aInstance A pointer to an OpenThread instance. 822 * @param[in] aCallback A pointer to callback handler function. 823 * 824 */ 825 void otThreadRegisterNeighborTableCallback(otInstance *aInstance, otNeighborTableCallback aCallback); 826 827 /** 828 * Sets whether the device was commissioned using CCM. 829 * 830 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used by Thread Test Harness 831 * to indicate whether this device was commissioned using CCM. 832 * 833 * @param[in] aInstance A pointer to an OpenThread instance. 834 * @param[in] aEnabled TRUE if the device was commissioned using CCM, FALSE otherwise. 835 * 836 */ 837 void otThreadSetCcmEnabled(otInstance *aInstance, bool aEnabled); 838 839 /** 840 * Sets whether the Security Policy TLV version-threshold for routing (VR field) is enabled. 841 * 842 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used by Thread Test Harness 843 * to indicate that thread protocol version check VR should be skipped. 844 * 845 * @param[in] aInstance A pointer to an OpenThread instance. 846 * @param[in] aEnabled TRUE to enable Security Policy TLV version-threshold for routing, FALSE otherwise. 847 * 848 */ 849 void otThreadSetThreadVersionCheckEnabled(otInstance *aInstance, bool aEnabled); 850 851 /** 852 * Gets the range of router IDs that are allowed to assign to nodes within the thread network. 853 * 854 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used for test purpose. All the 855 * router IDs in the range [aMinRouterId, aMaxRouterId] are allowed. 856 * 857 * @param[in] aInstance A pointer to an OpenThread instance. 858 * @param[out] aMinRouterId The minimum router ID. 859 * @param[out] aMaxRouterId The maximum router ID. 860 * 861 * @sa otThreadSetRouterIdRange 862 * 863 */ 864 void otThreadGetRouterIdRange(otInstance *aInstance, uint8_t *aMinRouterId, uint8_t *aMaxRouterId); 865 866 /** 867 * Sets the range of router IDs that are allowed to assign to nodes within the thread network. 868 * 869 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used for test purpose. All the 870 * router IDs in the range [aMinRouterId, aMaxRouterId] are allowed. 871 * 872 * @param[in] aInstance A pointer to an OpenThread instance. 873 * @param[in] aMinRouterId The minimum router ID. 874 * @param[in] aMaxRouterId The maximum router ID. 875 * 876 * @retval OT_ERROR_NONE Successfully set the range. 877 * @retval OT_ERROR_INVALID_ARGS aMinRouterId > aMaxRouterId, or the range is not covered by [0, 62]. 878 * 879 * @sa otThreadGetRouterIdRange 880 * 881 */ 882 otError otThreadSetRouterIdRange(otInstance *aInstance, uint8_t aMinRouterId, uint8_t aMaxRouterId); 883 884 /** 885 * Gets the current Interval Max value used by Advertisement trickle timer. 886 * 887 * This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is intended for testing only. 888 * 889 * @returns The Interval Max of Advertisement trickle timer in milliseconds. 890 * 891 */ 892 uint32_t otThreadGetAdvertisementTrickleIntervalMax(otInstance *aInstance); 893 894 /** 895 * Indicates whether or not a Router ID is currently allocated. 896 * 897 * @param[in] aInstance A pointer to an OpenThread instance. 898 * @param[in] aRouterId The router ID to check. 899 * 900 * @retval TRUE The @p aRouterId is allocated. 901 * @retval FALSE The @p aRouterId is not allocated. 902 * 903 */ 904 bool otThreadIsRouterIdAllocated(otInstance *aInstance, uint8_t aRouterId); 905 906 /** 907 * Gets the next hop and path cost towards a given RLOC16 destination. 908 * 909 * Can be used with either @p aNextHopRloc16 or @p aPathCost being NULL indicating caller does not want 910 * to get the value. 911 * 912 * @param[in] aInstance A pointer to an OpenThread instance. 913 * @param[in] aDesRloct16 The RLOC16 of destination. 914 * @param[out] aNextHopRloc16 A pointer to return RLOC16 of next hop, 0xfffe if no next hop. 915 * @param[out] aPathCost A pointer to return path cost towards destination. 916 * 917 */ 918 void otThreadGetNextHopAndPathCost(otInstance *aInstance, 919 uint16_t aDestRloc16, 920 uint16_t *aNextHopRloc16, 921 uint8_t *aPathCost); 922 923 /** 924 * @} 925 * 926 */ 927 928 #ifdef __cplusplus 929 } // extern "C" 930 #endif 931 932 #endif // OPENTHREAD_THREAD_FTD_H_ 933
