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