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 * If the device is not attached, this API will force the device to start as the leader of the network. This use case 488 * is only intended for testing and demo purposes, and using the API while the device is detached can make a production 489 * application non-compliant with the Thread Specification. 490 * 491 * If the device is already attached, this API can be used to try to take over as the leader, creating a new partition. 492 * For this to work, the local leader weight (`otThreadGetLocalLeaderWeight()`) must be larger than the weight of the 493 * current leader (`otThreadGetLeaderWeight()`). If it is not, `OT_ERROR_NOT_CAPABLE` is returned to indicate to the 494 * caller that they need to adjust the weight. 495 * 496 * Taking over the leader role in this way is only allowed when triggered by an explicit user action. Using this API 497 * without such user action can make a production application non-compliant with the Thread Specification. 498 * 499 * @param[in] aInstance A pointer to an OpenThread instance. 500 * 501 * @retval OT_ERROR_NONE Successfully became a leader and started a new partition, or was leader already. 502 * @retval OT_ERROR_INVALID_STATE Thread is disabled. 503 * @retval OT_ERROR_NOT_CAPABLE Device cannot override the current leader due to its local leader weight being same 504 * or smaller than current leader's weight, or device is not router eligible. 505 */ 506 otError otThreadBecomeLeader(otInstance *aInstance); 507 508 /** 509 * Get the ROUTER_DOWNGRADE_THRESHOLD parameter used in the Router role. 510 * 511 * @param[in] aInstance A pointer to an OpenThread instance. 512 * 513 * @returns The ROUTER_DOWNGRADE_THRESHOLD value. 514 * 515 * @sa otThreadSetRouterDowngradeThreshold 516 * 517 */ 518 uint8_t otThreadGetRouterDowngradeThreshold(otInstance *aInstance); 519 520 /** 521 * Set the ROUTER_DOWNGRADE_THRESHOLD parameter used in the Leader role. 522 * 523 * @note This API is reserved for testing and demo purposes only. Changing settings with 524 * this API will render a production application non-compliant with the Thread Specification. 525 * 526 * @param[in] aInstance A pointer to an OpenThread instance. 527 * @param[in] aThreshold The ROUTER_DOWNGRADE_THRESHOLD value. 528 * 529 * @sa otThreadGetRouterDowngradeThreshold 530 * 531 */ 532 void otThreadSetRouterDowngradeThreshold(otInstance *aInstance, uint8_t aThreshold); 533 534 /** 535 * Get the ROUTER_SELECTION_JITTER parameter used in the REED/Router role. 536 * 537 * @param[in] aInstance A pointer to an OpenThread instance. 538 * 539 * @returns The ROUTER_SELECTION_JITTER value. 540 * 541 * @sa otThreadSetRouterSelectionJitter 542 * 543 */ 544 uint8_t otThreadGetRouterSelectionJitter(otInstance *aInstance); 545 546 /** 547 * Set the ROUTER_SELECTION_JITTER parameter used in the REED/Router role. 548 * 549 * @note This API is reserved for testing and demo purposes only. Changing settings with 550 * this API will render a production application non-compliant with the Thread Specification. 551 * 552 * @param[in] aInstance A pointer to an OpenThread instance. 553 * @param[in] aRouterJitter The ROUTER_SELECTION_JITTER value. 554 * 555 * @sa otThreadGetRouterSelectionJitter 556 * 557 */ 558 void otThreadSetRouterSelectionJitter(otInstance *aInstance, uint8_t aRouterJitter); 559 560 /** 561 * Gets diagnostic information for an attached Child by its Child ID or RLOC16. 562 * 563 * @param[in] aInstance A pointer to an OpenThread instance. 564 * @param[in] aChildId The Child ID or RLOC16 for the attached child. 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 ID. 568 * @retval OT_ERROR_NOT_FOUND No valid child with this Child ID. 569 * @retval OT_ERROR_INVALID_ARGS If @p aChildInfo is NULL. 570 * 571 */ 572 otError otThreadGetChildInfoById(otInstance *aInstance, uint16_t aChildId, otChildInfo *aChildInfo); 573 574 /** 575 * The function retains diagnostic information for an attached Child by the internal table index. 576 * 577 * @param[in] aInstance A pointer to an OpenThread instance. 578 * @param[in] aChildIndex The table index. 579 * @param[out] aChildInfo A pointer to where the child information is placed. 580 * 581 * @retval OT_ERROR_NONE @p aChildInfo was successfully updated with the info for the given index. 582 * @retval OT_ERROR_NOT_FOUND No valid child at this index. 583 * @retval OT_ERROR_INVALID_ARGS Either @p aChildInfo is NULL, or @p aChildIndex is out of range (higher 584 * than max table index). 585 * 586 * @sa otGetMaxAllowedChildren 587 * 588 */ 589 otError otThreadGetChildInfoByIndex(otInstance *aInstance, uint16_t aChildIndex, otChildInfo *aChildInfo); 590 591 /** 592 * Gets the next IPv6 address (using an iterator) for a given child. 593 * 594 * @param[in] aInstance A pointer to an OpenThread instance. 595 * @param[in] aChildIndex The child index. 596 * @param[in,out] aIterator A pointer to the iterator. On success the iterator will be updated to point to next 597 * entry in the list. To get the first IPv6 address the iterator should be set to 598 * OT_CHILD_IP6_ADDRESS_ITERATOR_INIT. 599 * @param[out] aAddress A pointer to an IPv6 address where the child's next address is placed (on success). 600 * 601 * @retval OT_ERROR_NONE Successfully found the next IPv6 address (@p aAddress was successfully updated). 602 * @retval OT_ERROR_NOT_FOUND The child has no subsequent IPv6 address entry. 603 * @retval OT_ERROR_INVALID_ARGS @p aIterator or @p aAddress are NULL, or child at @p aChildIndex is not valid. 604 * 605 * @sa otThreadGetChildInfoByIndex 606 * 607 */ 608 otError otThreadGetChildNextIp6Address(otInstance *aInstance, 609 uint16_t aChildIndex, 610 otChildIp6AddressIterator *aIterator, 611 otIp6Address *aAddress); 612 613 /** 614 * Get the current Router ID Sequence. 615 * 616 * @param[in] aInstance A pointer to an OpenThread instance. 617 * 618 * @returns The Router ID Sequence. 619 * 620 */ 621 uint8_t otThreadGetRouterIdSequence(otInstance *aInstance); 622 623 /** 624 * The function returns the maximum allowed router ID 625 * 626 * @param[in] aInstance A pointer to an OpenThread instance. 627 * 628 * @returns The maximum allowed router ID. 629 * 630 */ 631 uint8_t otThreadGetMaxRouterId(otInstance *aInstance); 632 633 /** 634 * The function retains diagnostic information for a given Thread Router. 635 * 636 * @param[in] aInstance A pointer to an OpenThread instance. 637 * @param[in] aRouterId The router ID or RLOC16 for a given router. 638 * @param[out] aRouterInfo A pointer to where the router information is placed. 639 * 640 * @retval OT_ERROR_NONE Successfully retrieved the router info for given id. 641 * @retval OT_ERROR_NOT_FOUND No router entry with the given id. 642 * @retval OT_ERROR_INVALID_ARGS @p aRouterInfo is NULL. 643 * 644 */ 645 otError otThreadGetRouterInfo(otInstance *aInstance, uint16_t aRouterId, otRouterInfo *aRouterInfo); 646 647 /** 648 * Gets the next EID cache entry (using an iterator). 649 * 650 * @param[in] aInstance A pointer to an OpenThread instance. 651 * @param[out] aEntryInfo A pointer to where the EID cache entry information is placed. 652 * @param[in,out] aIterator A pointer to an iterator. It will be updated to point to next entry on success. To get 653 * the first entry, initialize the iterator by setting all its fields to zero 654 * (e.g., `memset` the iterator structure to zero). 655 * 656 * @retval OT_ERROR_NONE Successfully populated @p aEntryInfo for next EID cache entry. 657 * @retval OT_ERROR_NOT_FOUND No more entries in the address cache table. 658 * 659 */ 660 otError otThreadGetNextCacheEntry(otInstance *aInstance, otCacheEntryInfo *aEntryInfo, otCacheEntryIterator *aIterator); 661 662 /** 663 * Get the Thread PSKc 664 * 665 * @param[in] aInstance A pointer to an OpenThread instance. 666 * @param[out] aPskc A pointer to an `otPskc` to return the retrieved Thread PSKc. 667 * 668 * @sa otThreadSetPskc 669 * 670 */ 671 void otThreadGetPskc(otInstance *aInstance, otPskc *aPskc); 672 673 /** 674 * Get Key Reference to Thread PSKc stored 675 * 676 * Requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. 677 * 678 * @param[in] aInstance A pointer to an OpenThread instance. 679 * 680 * @returns Key Reference to PSKc 681 * 682 * @sa otThreadSetPskcRef 683 * 684 */ 685 otPskcRef otThreadGetPskcRef(otInstance *aInstance); 686 687 /** 688 * Set the Thread PSKc 689 * 690 * Will only succeed when Thread protocols are disabled. A successful 691 * call to this function will also invalidate the Active and Pending Operational Datasets in 692 * non-volatile memory. 693 * 694 * @param[in] aInstance A pointer to an OpenThread instance. 695 * @param[in] aPskc A pointer to the new Thread PSKc. 696 * 697 * @retval OT_ERROR_NONE Successfully set the Thread PSKc. 698 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 699 * 700 * @sa otThreadGetPskc 701 * 702 */ 703 otError otThreadSetPskc(otInstance *aInstance, const otPskc *aPskc); 704 705 /** 706 * Set the Key Reference to the Thread PSKc 707 * 708 * Requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. 709 * 710 * Will only succeed when Thread protocols are disabled. Upon success, 711 * this will also invalidate the Active and Pending Operational Datasets in 712 * non-volatile memory. 713 * 714 * @param[in] aInstance A pointer to an OpenThread instance. 715 * @param[in] aKeyRef Key Reference to the new Thread PSKc. 716 * 717 * @retval OT_ERROR_NONE Successfully set the Thread PSKc. 718 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 719 * 720 * @sa otThreadGetPskcRef 721 * 722 */ 723 otError otThreadSetPskcRef(otInstance *aInstance, otPskcRef aKeyRef); 724 725 /** 726 * Get the assigned parent priority. 727 * 728 * @param[in] aInstance A pointer to an OpenThread instance. 729 * 730 * @returns The assigned parent priority value, -2 means not assigned. 731 * 732 * @sa otThreadSetParentPriority 733 * 734 */ 735 int8_t otThreadGetParentPriority(otInstance *aInstance); 736 737 /** 738 * Set the parent priority. 739 * 740 * @note This API is reserved for testing and demo purposes only. Changing settings with 741 * this API will render a production application non-compliant with the Thread Specification. 742 * 743 * @param[in] aInstance A pointer to an OpenThread instance. 744 * @param[in] aParentPriority The parent priority value. 745 * 746 * @retval OT_ERROR_NONE Successfully set the parent priority. 747 * @retval OT_ERROR_INVALID_ARGS If the parent priority value is not among 1, 0, -1 and -2. 748 * 749 * @sa otThreadGetParentPriority 750 * 751 */ 752 otError otThreadSetParentPriority(otInstance *aInstance, int8_t aParentPriority); 753 754 /** 755 * Gets the maximum number of IP addresses that each MTD child may register with this device as parent. 756 * 757 * @param[in] aInstance A pointer to an OpenThread instance. 758 * 759 * @returns The maximum number of IP addresses that each MTD child may register with this device as parent. 760 * 761 * @sa otThreadSetMaxChildIpAddresses 762 * 763 */ 764 uint8_t otThreadGetMaxChildIpAddresses(otInstance *aInstance); 765 766 /** 767 * Sets or restores the maximum number of IP addresses that each MTD child may register with this 768 * device as parent. 769 * 770 * Pass `0` to clear the setting and restore the default. 771 * 772 * Available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 773 * 774 * @note Only used by Thread Test Harness to limit the address registrations of the reference 775 * parent in order to test the MTD DUT reaction. 776 * 777 * @param[in] aInstance A pointer to an OpenThread instance. 778 * @param[in] aMaxIpAddresses The maximum number of IP addresses that each MTD child may register with this 779 * device as parent. 0 to clear the setting and restore the default. 780 * 781 * @retval OT_ERROR_NONE Successfully set/cleared the number. 782 * @retval OT_ERROR_INVALID_ARGS If exceeds the allowed maximum number. 783 * 784 * @sa otThreadGetMaxChildIpAddresses 785 * 786 */ 787 otError otThreadSetMaxChildIpAddresses(otInstance *aInstance, uint8_t aMaxIpAddresses); 788 789 /** 790 * Defines the constants used in `otNeighborTableCallback` to indicate changes in neighbor table. 791 * 792 */ 793 typedef enum 794 { 795 OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED, ///< A child is being added. 796 OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED, ///< A child is being removed. 797 OT_NEIGHBOR_TABLE_EVENT_CHILD_MODE_CHANGED, ///< An existing child's mode is changed. 798 OT_NEIGHBOR_TABLE_EVENT_ROUTER_ADDED, ///< A router is being added. 799 OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED, ///< A router is being removed. 800 } otNeighborTableEvent; 801 802 /** 803 * Represent a neighbor table entry info (child or router) and is used as a parameter in the neighbor table 804 * callback `otNeighborTableCallback`. 805 * 806 */ 807 typedef struct 808 { 809 otInstance *mInstance; ///< The OpenThread instance. 810 union 811 { 812 otChildInfo mChild; ///< The child neighbor info. 813 otNeighborInfo mRouter; ///< The router neighbor info. 814 } mInfo; 815 } otNeighborTableEntryInfo; 816 817 /** 818 * Pointer is called to notify that there is a change in the neighbor table. 819 * 820 * @param[in] aEvent A event flag. 821 * @param[in] aEntryInfo A pointer to table entry info. 822 * 823 */ 824 typedef void (*otNeighborTableCallback)(otNeighborTableEvent aEvent, const otNeighborTableEntryInfo *aEntryInfo); 825 826 /** 827 * Registers a neighbor table callback function. 828 * 829 * The provided callback (if non-NULL) will be invoked when there is a change in the neighbor table (e.g., a child or a 830 * router neighbor entry is being added/removed or an existing child's mode is changed). 831 * 832 * Subsequent calls to this method will overwrite the previous callback. Note that this callback in invoked while the 833 * neighbor/child table is being updated and always before the `otStateChangedCallback`. 834 * 835 * @param[in] aInstance A pointer to an OpenThread instance. 836 * @param[in] aCallback A pointer to callback handler function. 837 * 838 */ 839 void otThreadRegisterNeighborTableCallback(otInstance *aInstance, otNeighborTableCallback aCallback); 840 841 /** 842 * Sets whether the device was commissioned using CCM. 843 * 844 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used by Thread Test Harness 845 * to indicate whether this device was commissioned using CCM. 846 * 847 * @param[in] aInstance A pointer to an OpenThread instance. 848 * @param[in] aEnabled TRUE if the device was commissioned using CCM, FALSE otherwise. 849 * 850 */ 851 void otThreadSetCcmEnabled(otInstance *aInstance, bool aEnabled); 852 853 /** 854 * Sets whether the Security Policy TLV version-threshold for routing (VR field) is enabled. 855 * 856 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used by Thread Test Harness 857 * to indicate that thread protocol version check VR should be skipped. 858 * 859 * @param[in] aInstance A pointer to an OpenThread instance. 860 * @param[in] aEnabled TRUE to enable Security Policy TLV version-threshold for routing, FALSE otherwise. 861 * 862 */ 863 void otThreadSetThreadVersionCheckEnabled(otInstance *aInstance, bool aEnabled); 864 865 /** 866 * Enables or disables the filter to drop TMF UDP messages from untrusted origin. 867 * 868 * TMF messages are only trusted when they originate from a trusted source, such as the Thread interface. In 869 * special cases, such as when a device uses platform UDP socket to send TMF messages, they will be dropped due 870 * to untrusted origin. This filter is enabled by default. 871 * 872 * When this filter is disabled, UDP messages sent to the TMF port that originate from untrusted origin (such as 873 * host, CLI or an external IPv6 node) will be allowed. 874 * 875 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` and is only used by Thread Test Harness 876 * to test network behavior by sending special TMF messages from the CLI on a POSIX host. 877 * 878 * @param[in] aInstance A pointer to an OpenThread instance. 879 * @param[in] aEnabled TRUE to enable filter, FALSE otherwise. 880 * 881 */ 882 void otThreadSetTmfOriginFilterEnabled(otInstance *aInstance, bool aEnabled); 883 884 /** 885 * Indicates whether the filter that drops TMF UDP messages from untrusted origin is enabled or not. 886 * 887 * This is intended for testing only and available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` config is enabled. 888 * 889 * @retval TRUE The filter is enabled. 890 * @retval FALSE The filter is not enabled. 891 * 892 */ 893 bool otThreadIsTmfOriginFilterEnabled(otInstance *aInstance); 894 895 /** 896 * Gets the range of router IDs that are allowed to assign to nodes within the thread network. 897 * 898 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used for test purpose. All the 899 * router IDs in the range [aMinRouterId, aMaxRouterId] are allowed. 900 * 901 * @param[in] aInstance A pointer to an OpenThread instance. 902 * @param[out] aMinRouterId The minimum router ID. 903 * @param[out] aMaxRouterId The maximum router ID. 904 * 905 * @sa otThreadSetRouterIdRange 906 * 907 */ 908 void otThreadGetRouterIdRange(otInstance *aInstance, uint8_t *aMinRouterId, uint8_t *aMaxRouterId); 909 910 /** 911 * Sets the range of router IDs that are allowed to assign to nodes within the thread network. 912 * 913 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used for test purpose. All the 914 * router IDs in the range [aMinRouterId, aMaxRouterId] are allowed. 915 * 916 * @param[in] aInstance A pointer to an OpenThread instance. 917 * @param[in] aMinRouterId The minimum router ID. 918 * @param[in] aMaxRouterId The maximum router ID. 919 * 920 * @retval OT_ERROR_NONE Successfully set the range. 921 * @retval OT_ERROR_INVALID_ARGS aMinRouterId > aMaxRouterId, or the range is not covered by [0, 62]. 922 * 923 * @sa otThreadGetRouterIdRange 924 * 925 */ 926 otError otThreadSetRouterIdRange(otInstance *aInstance, uint8_t aMinRouterId, uint8_t aMaxRouterId); 927 928 /** 929 * Gets the current Interval Max value used by Advertisement trickle timer. 930 * 931 * This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is intended for testing only. 932 * 933 * @returns The Interval Max of Advertisement trickle timer in milliseconds. 934 * 935 */ 936 uint32_t otThreadGetAdvertisementTrickleIntervalMax(otInstance *aInstance); 937 938 /** 939 * Indicates whether or not a Router ID is currently allocated. 940 * 941 * @param[in] aInstance A pointer to an OpenThread instance. 942 * @param[in] aRouterId The router ID to check. 943 * 944 * @retval TRUE The @p aRouterId is allocated. 945 * @retval FALSE The @p aRouterId is not allocated. 946 * 947 */ 948 bool otThreadIsRouterIdAllocated(otInstance *aInstance, uint8_t aRouterId); 949 950 /** 951 * Gets the next hop and path cost towards a given RLOC16 destination. 952 * 953 * Can be used with either @p aNextHopRloc16 or @p aPathCost being NULL indicating caller does not want 954 * to get the value. 955 * 956 * @param[in] aInstance A pointer to an OpenThread instance. 957 * @param[in] aDestRloc16 The RLOC16 of destination. 958 * @param[out] aNextHopRloc16 A pointer to return RLOC16 of next hop, 0xfffe if no next hop. 959 * @param[out] aPathCost A pointer to return path cost towards destination. 960 * 961 */ 962 void otThreadGetNextHopAndPathCost(otInstance *aInstance, 963 uint16_t aDestRloc16, 964 uint16_t *aNextHopRloc16, 965 uint8_t *aPathCost); 966 967 /** 968 * @} 969 * 970 */ 971 972 #ifdef __cplusplus 973 } // extern "C" 974 #endif 975 976 #endif // OPENTHREAD_THREAD_FTD_H_ 977
