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