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; ///< Time last heard 62 uint16_t mRloc16; ///< RLOC16 63 uint16_t mChildId; ///< Child ID 64 uint8_t mNetworkDataVersion; ///< Network Data Version 65 uint8_t mLinkQualityIn; ///< Link Quality In 66 int8_t mAverageRssi; ///< Average RSSI 67 int8_t mLastRssi; ///< Last observed RSSI 68 uint16_t mFrameErrorRate; ///< Frame error rate (0xffff->100%). Requires error tracking feature. 69 uint16_t mMessageErrorRate; ///< (IPv6) msg error rate (0xffff->100%). Requires error tracking feature. 70 uint16_t mQueuedMessageCnt; ///< Number of queued messages for the child. 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 * This enumeration defines the EID cache entry state. 85 * 86 */ 87 typedef enum otCacheEntryState 88 { 89 OT_CACHE_ENTRY_STATE_CACHED = 0, // Entry is cached and in-use. 90 OT_CACHE_ENTRY_STATE_SNOOPED = 1, // Entry is created by snoop optimization (inspection of received msg). 91 OT_CACHE_ENTRY_STATE_QUERY = 2, // Entry represents an ongoing query for the EID. 92 OT_CACHE_ENTRY_STATE_RETRY_QUERY = 3, // Entry is in retry wait mode (a prior query did not get a response). 93 } otCacheEntryState; 94 95 /** 96 * This structure represents an EID cache entry. 97 * 98 */ 99 typedef struct otCacheEntryInfo 100 { 101 otIp6Address mTarget; ///< Target EID 102 otShortAddress mRloc16; ///< RLOC16 103 otCacheEntryState mState; ///< Entry state 104 bool mCanEvict : 1; ///< Indicates whether the entry can be evicted. 105 bool mValidLastTrans : 1; ///< Indicates whether last transaction time and ML-EID are valid. 106 uint32_t mLastTransTime; ///< Last transaction time (applicable in cached state). 107 otIp6Address mMeshLocalEid; ///< Mesh Local EID (applicable if entry in cached state). 108 uint16_t mTimeout; ///< Timeout in seconds (applicable if in snooped/query/retry-query states). 109 uint16_t mRetryDelay; ///< Retry delay in seconds (applicable if in query-retry state). 110 } otCacheEntryInfo; 111 112 /** 113 * This type represents an iterator used for iterating through the EID cache table entries. 114 * 115 * To initialize the iterator and start from the first entry in the cache table, set all its fields in the structure to 116 * zero (e.g., `memset` the iterator to zero). 117 * 118 */ 119 typedef struct otCacheEntryIterator 120 { 121 const void *mData[2]; ///< Opaque data used by the core implementation. Should not be changed by user. 122 } otCacheEntryIterator; 123 124 /** 125 * Get the maximum number of children currently allowed. 126 * 127 * @param[in] aInstance A pointer to an OpenThread instance. 128 * 129 * @returns The maximum number of children currently allowed. 130 * 131 * @sa otThreadSetMaxAllowedChildren 132 * 133 */ 134 uint16_t otThreadGetMaxAllowedChildren(otInstance *aInstance); 135 136 /** 137 * Set the maximum number of children currently allowed. 138 * 139 * This parameter can only be set when Thread protocol operation has been stopped. 140 * 141 * @param[in] aInstance A pointer to an OpenThread instance. 142 * @param[in] aMaxChildren The maximum allowed children. 143 * 144 * @retval OT_ERROR_NONE Successfully set the max. 145 * @retval OT_ERROR_INVALID_ARGS If @p aMaxChildren is not in the range [1, OPENTHREAD_CONFIG_MLE_MAX_CHILDREN]. 146 * @retval OT_ERROR_INVALID_STATE If Thread isn't stopped. 147 * 148 * @sa otThreadGetMaxAllowedChildren 149 * 150 */ 151 otError otThreadSetMaxAllowedChildren(otInstance *aInstance, uint16_t aMaxChildren); 152 153 /** 154 * This method indicates whether or not the device is router-eligible. 155 * 156 * @param[in] aInstance A pointer to an OpenThread instance. 157 * 158 * @retval TRUE If device is router-eligible. 159 * @retval FALSE If device is not router-eligible. 160 * 161 */ 162 bool otThreadIsRouterEligible(otInstance *aInstance); 163 164 /** 165 * This function sets whether or not the device is router-eligible. 166 * 167 * If @p aEligible is false and the device is currently operating as a router, this call will cause the device to 168 * detach and attempt to reattach as a child. 169 * 170 * @param[in] aInstance A pointer to an OpenThread instance. 171 * @param[in] aEligible TRUE to configure the device as router-eligible, FALSE otherwise. 172 * 173 * @retval OT_ERROR_NONE Successfully set the router-eligible configuration. 174 * @retval OT_ERROR_NOT_CAPABLE The device is not capable of becoming a router. 175 * 176 */ 177 otError otThreadSetRouterEligible(otInstance *aInstance, bool aEligible); 178 179 /** 180 * Set the preferred Router Id. 181 * 182 * Upon becoming a router/leader the node attempts to use this Router Id. If the preferred Router Id is not set or if 183 * it can not be used, a randomly generated router id is picked. This property can be set only when the device role is 184 * either detached or disabled. 185 * 186 * @note This API is reserved for testing and demo purposes only. Changing settings with 187 * this API will render a production application non-compliant with the Thread Specification. 188 * 189 * @param[in] aInstance A pointer to an OpenThread instance. 190 * @param[in] aRouterId The preferred Router Id. 191 * 192 * @retval OT_ERROR_NONE Successfully set the preferred Router Id. 193 * @retval OT_ERROR_INVALID_STATE Could not set (role is not detached or disabled) 194 * 195 */ 196 otError otThreadSetPreferredRouterId(otInstance *aInstance, uint8_t aRouterId); 197 198 /** 199 * Get the Thread Leader Weight used when operating in the Leader role. 200 * 201 * @param[in] aInstance A pointer to an OpenThread instance. 202 * 203 * @returns The Thread Leader Weight value. 204 * 205 * @sa otThreadSetLeaderWeight 206 * 207 */ 208 uint8_t otThreadGetLocalLeaderWeight(otInstance *aInstance); 209 210 /** 211 * Set the Thread Leader Weight used when operating in the Leader role. 212 * 213 * @param[in] aInstance A pointer to an OpenThread instance. 214 * @param[in] aWeight The Thread Leader Weight value. 215 * 216 * @sa otThreadGetLeaderWeight 217 * 218 */ 219 void otThreadSetLocalLeaderWeight(otInstance *aInstance, uint8_t aWeight); 220 221 /** 222 * Get the preferred Thread Leader Partition Id used when operating in the Leader role. 223 * 224 * @param[in] aInstance A pointer to an OpenThread instance. 225 * 226 * @returns The Thread Leader Partition Id value. 227 * 228 */ 229 uint32_t otThreadGetPreferredLeaderPartitionId(otInstance *aInstance); 230 231 /** 232 * Set the preferred Thread Leader Partition Id used when operating in the Leader role. 233 * 234 * @param[in] aInstance A pointer to an OpenThread instance. 235 * @param[in] aPartitionId The Thread Leader Partition Id value. 236 * 237 */ 238 void otThreadSetPreferredLeaderPartitionId(otInstance *aInstance, uint32_t aPartitionId); 239 240 /** 241 * Get the Joiner UDP Port. 242 * 243 * @param[in] aInstance A pointer to an OpenThread instance. 244 * 245 * @returns The Joiner UDP Port number. 246 * 247 * @sa otThreadSetJoinerUdpPort 248 * 249 */ 250 uint16_t otThreadGetJoinerUdpPort(otInstance *aInstance); 251 252 /** 253 * Set the Joiner UDP Port. 254 * 255 * @param[in] aInstance A pointer to an OpenThread instance. 256 * @param[in] aJoinerUdpPort The Joiner UDP Port number. 257 * 258 * @retval OT_ERROR_NONE Successfully set the Joiner UDP Port. 259 * 260 * @sa otThreadGetJoinerUdpPort 261 * 262 */ 263 otError otThreadSetJoinerUdpPort(otInstance *aInstance, uint16_t aJoinerUdpPort); 264 265 /** 266 * Set Steering data out of band. 267 * 268 * Configuration option `OPENTHREAD_CONFIG_MLE_STEERING_DATA_SET_OOB_ENABLE` should be set to enable setting of steering 269 * data out of band. 270 * 271 * @param[in] aInstance A pointer to an OpenThread instance. 272 * @param[in] aExtAddress Address used to update the steering data. 273 * All zeros to clear the steering data (no steering data). 274 * All 0xFFs to set steering data/bloom filter to accept/allow all. 275 * A specific EUI64 which is then added to current steering data/bloom filter. 276 * 277 */ 278 void otThreadSetSteeringData(otInstance *aInstance, const otExtAddress *aExtAddress); 279 280 /** 281 * Get the CONTEXT_ID_REUSE_DELAY parameter used in the Leader role. 282 * 283 * @param[in] aInstance A pointer to an OpenThread instance. 284 * 285 * @returns The CONTEXT_ID_REUSE_DELAY value. 286 * 287 * @sa otThreadSetContextIdReuseDelay 288 * 289 */ 290 uint32_t otThreadGetContextIdReuseDelay(otInstance *aInstance); 291 292 /** 293 * Set the CONTEXT_ID_REUSE_DELAY parameter used in the Leader role. 294 * 295 * @note This API is reserved for testing and demo purposes only. Changing settings with 296 * this API will render a production application non-compliant with the Thread Specification. 297 * 298 * @param[in] aInstance A pointer to an OpenThread instance. 299 * @param[in] aDelay The CONTEXT_ID_REUSE_DELAY value. 300 * 301 * @sa otThreadGetContextIdReuseDelay 302 * 303 */ 304 void otThreadSetContextIdReuseDelay(otInstance *aInstance, uint32_t aDelay); 305 306 /** 307 * Get the NETWORK_ID_TIMEOUT parameter used in the Router role. 308 * 309 * @note This API is reserved for testing and demo purposes only. Changing settings with 310 * this API will render a production application non-compliant with the Thread Specification. 311 * 312 * @param[in] aInstance A pointer to an OpenThread instance. 313 * 314 * @returns The NETWORK_ID_TIMEOUT value. 315 * 316 * @sa otThreadSetNetworkIdTimeout 317 * 318 */ 319 uint8_t otThreadGetNetworkIdTimeout(otInstance *aInstance); 320 321 /** 322 * Set the NETWORK_ID_TIMEOUT parameter used in the Leader role. 323 * 324 * @param[in] aInstance A pointer to an OpenThread instance. 325 * @param[in] aTimeout The NETWORK_ID_TIMEOUT value. 326 * 327 * @sa otThreadGetNetworkIdTimeout 328 * 329 */ 330 void otThreadSetNetworkIdTimeout(otInstance *aInstance, uint8_t aTimeout); 331 332 /** 333 * Get the ROUTER_UPGRADE_THRESHOLD parameter used in the REED role. 334 * 335 * @param[in] aInstance A pointer to an OpenThread instance. 336 * 337 * @returns The ROUTER_UPGRADE_THRESHOLD value. 338 * 339 * @sa otThreadSetRouterUpgradeThreshold 340 * 341 */ 342 uint8_t otThreadGetRouterUpgradeThreshold(otInstance *aInstance); 343 344 /** 345 * Set the ROUTER_UPGRADE_THRESHOLD parameter used in the Leader role. 346 * 347 * @note This API is reserved for testing and demo purposes only. Changing settings with 348 * this API will render a production application non-compliant with the Thread Specification. 349 * 350 * @param[in] aInstance A pointer to an OpenThread instance. 351 * @param[in] aThreshold The ROUTER_UPGRADE_THRESHOLD value. 352 * 353 * @sa otThreadGetRouterUpgradeThreshold 354 * 355 */ 356 void otThreadSetRouterUpgradeThreshold(otInstance *aInstance, uint8_t aThreshold); 357 358 /** 359 * Release a Router ID that has been allocated by the device in the Leader role. 360 * 361 * @note This API is reserved for testing and demo purposes only. Changing settings with 362 * this API will render a production application non-compliant with the Thread Specification. 363 * 364 * @param[in] aInstance A pointer to an OpenThread instance. 365 * @param[in] aRouterId The Router ID to release. Valid range is [0, 62]. 366 * 367 * @retval OT_ERROR_NONE Successfully released the router id. 368 * @retval OT_ERROR_INVALID_ARGS @p aRouterId is not in the range [0, 62]. 369 * @retval OT_ERROR_INVALID_STATE The device is not currently operating as a leader. 370 * @retval OT_ERROR_NOT_FOUND The router id is not currently allocated. 371 * 372 */ 373 otError otThreadReleaseRouterId(otInstance *aInstance, uint8_t aRouterId); 374 375 /** 376 * Attempt to become a router. 377 * 378 * @note This API is reserved for testing and demo purposes only. Changing settings with 379 * this API will render a production application non-compliant with the Thread Specification. 380 * 381 * @param[in] aInstance A pointer to an OpenThread instance. 382 * 383 * @retval OT_ERROR_NONE Successfully begin attempt to become a router. 384 * @retval OT_ERROR_INVALID_STATE Thread is disabled. 385 */ 386 otError otThreadBecomeRouter(otInstance *aInstance); 387 388 /** 389 * Become a leader and start a new partition. 390 * 391 * @note This API is reserved for testing and demo purposes only. Changing settings with 392 * this API will render a production application non-compliant with the Thread Specification. 393 * 394 * @param[in] aInstance A pointer to an OpenThread instance. 395 * 396 * @retval OT_ERROR_NONE Successfully became a leader and started a new partition. 397 * @retval OT_ERROR_INVALID_STATE Thread is disabled. 398 */ 399 otError otThreadBecomeLeader(otInstance *aInstance); 400 401 /** 402 * Get the ROUTER_DOWNGRADE_THRESHOLD parameter used in the Router role. 403 * 404 * @param[in] aInstance A pointer to an OpenThread instance. 405 * 406 * @returns The ROUTER_DOWNGRADE_THRESHOLD value. 407 * 408 * @sa otThreadSetRouterDowngradeThreshold 409 * 410 */ 411 uint8_t otThreadGetRouterDowngradeThreshold(otInstance *aInstance); 412 413 /** 414 * Set the ROUTER_DOWNGRADE_THRESHOLD parameter used in the Leader role. 415 * 416 * @note This API is reserved for testing and demo purposes only. Changing settings with 417 * this API will render a production application non-compliant with the Thread Specification. 418 * 419 * @param[in] aInstance A pointer to an OpenThread instance. 420 * @param[in] aThreshold The ROUTER_DOWNGRADE_THRESHOLD value. 421 * 422 * @sa otThreadGetRouterDowngradeThreshold 423 * 424 */ 425 void otThreadSetRouterDowngradeThreshold(otInstance *aInstance, uint8_t aThreshold); 426 427 /** 428 * Get the ROUTER_SELECTION_JITTER parameter used in the REED/Router role. 429 * 430 * @param[in] aInstance A pointer to an OpenThread instance. 431 * 432 * @returns The ROUTER_SELECTION_JITTER value. 433 * 434 * @sa otThreadSetRouterSelectionJitter 435 * 436 */ 437 uint8_t otThreadGetRouterSelectionJitter(otInstance *aInstance); 438 439 /** 440 * Set the ROUTER_SELECTION_JITTER parameter used in the REED/Router role. 441 * 442 * @note This API is reserved for testing and demo purposes only. Changing settings with 443 * this API will render a production application non-compliant with the Thread Specification. 444 * 445 * @param[in] aInstance A pointer to an OpenThread instance. 446 * @param[in] aRouterJitter The ROUTER_SELECTION_JITTER value. 447 * 448 * @sa otThreadGetRouterSelectionJitter 449 * 450 */ 451 void otThreadSetRouterSelectionJitter(otInstance *aInstance, uint8_t aRouterJitter); 452 453 /** 454 * The function retains diagnostic information for an attached Child by its Child ID or RLOC16. 455 * 456 * @param[in] aInstance A pointer to an OpenThread instance. 457 * @param[in] aChildId The Child ID or RLOC16 for the attached child. 458 * @param[out] aChildInfo A pointer to where the child information is placed. 459 * 460 * @retval OT_ERROR_NONE @p aChildInfo was successfully updated with the info for the given ID. 461 * @retval OT_ERROR_NOT_FOUND No valid child with this Child ID. 462 * @retval OT_ERROR_INVALID_ARGS If @p aChildInfo is NULL. 463 * 464 */ 465 otError otThreadGetChildInfoById(otInstance *aInstance, uint16_t aChildId, otChildInfo *aChildInfo); 466 467 /** 468 * The function retains diagnostic information for an attached Child by the internal table index. 469 * 470 * @param[in] aInstance A pointer to an OpenThread instance. 471 * @param[in] aChildIndex The table index. 472 * @param[out] aChildInfo A pointer to where the child information is placed. 473 * 474 * @retval OT_ERROR_NONE @p aChildInfo was successfully updated with the info for the given index. 475 * @retval OT_ERROR_NOT_FOUND No valid child at this index. 476 * @retval OT_ERROR_INVALID_ARGS Either @p aChildInfo is NULL, or @p aChildIndex is out of range (higher 477 * than max table index). 478 * 479 * @sa otGetMaxAllowedChildren 480 * 481 */ 482 otError otThreadGetChildInfoByIndex(otInstance *aInstance, uint16_t aChildIndex, otChildInfo *aChildInfo); 483 484 /** 485 * This function gets the next IPv6 address (using an iterator) for a given child. 486 * 487 * @param[in] aInstance A pointer to an OpenThread instance. 488 * @param[in] aChildIndex The child index. 489 * @param[in,out] aIterator A pointer to the iterator. On success the iterator will be updated to point to next 490 * entry in the list. To get the first IPv6 address the iterator should be set to 491 * OT_CHILD_IP6_ADDRESS_ITERATOR_INIT. 492 * @param[out] aAddress A pointer to an IPv6 address where the child's next address is placed (on success). 493 * 494 * @retval OT_ERROR_NONE Successfully found the next IPv6 address (@p aAddress was successfully updated). 495 * @retval OT_ERROR_NOT_FOUND The child has no subsequent IPv6 address entry. 496 * @retval OT_ERROR_INVALID_ARGS @p aIterator or @p aAddress are NULL, or child at @p aChildIndex is not valid. 497 * 498 * @sa otThreadGetChildInfoByIndex 499 * 500 */ 501 otError otThreadGetChildNextIp6Address(otInstance * aInstance, 502 uint16_t aChildIndex, 503 otChildIp6AddressIterator *aIterator, 504 otIp6Address * aAddress); 505 506 /** 507 * Get the current Router ID Sequence. 508 * 509 * @param[in] aInstance A pointer to an OpenThread instance. 510 * 511 * @returns The Router ID Sequence. 512 * 513 */ 514 uint8_t otThreadGetRouterIdSequence(otInstance *aInstance); 515 516 /** 517 * The function returns the maximum allowed router ID 518 * 519 * @param[in] aInstance A pointer to an OpenThread instance. 520 * 521 * @returns The maximum allowed router ID. 522 * 523 */ 524 uint8_t otThreadGetMaxRouterId(otInstance *aInstance); 525 526 /** 527 * The function retains diagnostic information for a given Thread Router. 528 * 529 * @param[in] aInstance A pointer to an OpenThread instance. 530 * @param[in] aRouterId The router ID or RLOC16 for a given router. 531 * @param[out] aRouterInfo A pointer to where the router information is placed. 532 * 533 * @retval OT_ERROR_NONE Successfully retrieved the router info for given id. 534 * @retval OT_ERROR_NOT_FOUND No router entry with the given id. 535 * @retval OT_ERROR_INVALID_ARGS @p aRouterInfo is NULL. 536 * 537 */ 538 otError otThreadGetRouterInfo(otInstance *aInstance, uint16_t aRouterId, otRouterInfo *aRouterInfo); 539 540 /** 541 * This function gets the next EID cache entry (using an iterator). 542 * 543 * @param[in] aInstance A pointer to an OpenThread instance. 544 * @param[out] aEntryInfo A pointer to where the EID cache entry information is placed. 545 * @param[in,out] aIterator A pointer to an iterator. It will be updated to point to next entry on success. To get 546 * the first entry, initialize the iterator by setting all its fields to zero 547 * (e.g., `memset` the iterator structure to zero). 548 * 549 * @retval OT_ERROR_NONE Successfully populated @p aEntryInfo for next EID cache entry. 550 * @retval OT_ERROR_NOT_FOUND No more entries in the address cache table. 551 * 552 */ 553 otError otThreadGetNextCacheEntry(otInstance *aInstance, otCacheEntryInfo *aEntryInfo, otCacheEntryIterator *aIterator); 554 555 /** 556 * Get the Thread PSKc 557 * 558 * @param[in] aInstance A pointer to an OpenThread instance. 559 * @param[out] aPskc A pointer to an `otPskc` to return the retrieved Thread PSKc. 560 * 561 * @sa otThreadSetPskc 562 * 563 */ 564 void otThreadGetPskc(otInstance *aInstance, otPskc *aPskc); 565 566 /** 567 * Get Key Reference to Thread PSKc stored 568 * 569 * This function requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. 570 * 571 * @param[in] aInstance A pointer to an OpenThread instance. 572 * 573 * @returns Key Reference to PSKc 574 * 575 * @sa otThreadSetPskcRef 576 * 577 */ 578 otPskcRef otThreadGetPskcRef(otInstance *aInstance); 579 580 /** 581 * Set the Thread PSKc 582 * 583 * This function will only succeed when Thread protocols are disabled. A successful 584 * call to this function will also invalidate the Active and Pending Operational Datasets in 585 * non-volatile memory. 586 * 587 * @param[in] aInstance A pointer to an OpenThread instance. 588 * @param[in] aPskc A pointer to the new Thread PSKc. 589 * 590 * @retval OT_ERROR_NONE Successfully set the Thread PSKc. 591 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 592 * 593 * @sa otThreadGetPskc 594 * 595 */ 596 otError otThreadSetPskc(otInstance *aInstance, const otPskc *aPskc); 597 598 /** 599 * Set the Thread PSKc 600 * 601 * This function requires the build-time feature `OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE` to be enabled. 602 * 603 * This function will only succeed when Thread protocols are disabled. A successful 604 * call to this function will also invalidate the Active and Pending Operational Datasets in 605 * non-volatile memory. 606 * 607 * @param[in] aInstance A pointer to an OpenThread instance. 608 * @param[in] aKeyRef Key Reference to the new Thread PSKc. 609 * 610 * @retval OT_ERROR_NONE Successfully set the Thread PSKc. 611 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 612 * 613 * @sa otThreadGetPskcRef 614 * 615 */ 616 otError otThreadSetPskcRef(otInstance *aInstance, otPskcRef aKeyRef); 617 618 /** 619 * Get the assigned parent priority. 620 * 621 * @param[in] aInstance A pointer to an OpenThread instance. 622 * 623 * @returns The assigned parent priority value, -2 means not assigned. 624 * 625 * @sa otThreadSetParentPriority 626 * 627 */ 628 int8_t otThreadGetParentPriority(otInstance *aInstance); 629 630 /** 631 * Set the parent priority. 632 * 633 * @note This API is reserved for testing and demo purposes only. Changing settings with 634 * this API will render a production application non-compliant with the Thread Specification. 635 * 636 * @param[in] aInstance A pointer to an OpenThread instance. 637 * @param[in] aParentPriority The parent priority value. 638 * 639 * @retval OT_ERROR_NONE Successfully set the parent priority. 640 * @retval OT_ERROR_INVALID_ARGS If the parent priority value is not among 1, 0, -1 and -2. 641 * 642 * @sa otThreadGetParentPriority 643 * 644 */ 645 otError otThreadSetParentPriority(otInstance *aInstance, int8_t aParentPriority); 646 647 /** 648 * This function gets the maximum number of IP addresses that each MTD child may register with this device as parent. 649 * 650 * @param[in] aInstance A pointer to an OpenThread instance. 651 * 652 * @returns The maximum number of IP addresses that each MTD child may register with this device as parent. 653 * 654 * @sa otThreadSetMaxChildIpAddresses 655 * 656 */ 657 uint8_t otThreadGetMaxChildIpAddresses(otInstance *aInstance); 658 659 /** 660 * This function sets/restores the maximum number of IP addresses that each MTD child may register with this 661 * device as parent. 662 * 663 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used by Thread Test Harness 664 * to limit the address registrations of the reference parent in order to test the MTD DUT reaction. 665 * 666 * @param[in] aInstance A pointer to an OpenThread instance. 667 * @param[in] aMaxIpAddresses The maximum number of IP addresses that each MTD child may register with this 668 * device as parent. 0 to clear the setting and restore the default. 669 * 670 * @retval OT_ERROR_NONE Successfully set/cleared the number. 671 * @retval OT_ERROR_INVALID_ARGS If exceeds the allowed maximum number. 672 * 673 * @sa otThreadGetMaxChildIpAddresses 674 * 675 */ 676 otError otThreadSetMaxChildIpAddresses(otInstance *aInstance, uint8_t aMaxIpAddresses); 677 678 /** 679 * This enumeration defines the constants used in `otNeighborTableCallback` to indicate changes in neighbor table. 680 * 681 */ 682 typedef enum 683 { 684 OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED, ///< A child is being added. 685 OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED, ///< A child is being removed. 686 OT_NEIGHBOR_TABLE_EVENT_CHILD_MODE_CHANGED, ///< An existing child's mode is changed. 687 OT_NEIGHBOR_TABLE_EVENT_ROUTER_ADDED, ///< A router is being added. 688 OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED, ///< A router is being removed. 689 } otNeighborTableEvent; 690 691 /** 692 * This type represent a neighbor table entry info (child or router) and is used as a parameter in the neighbor table 693 * callback `otNeighborTableCallback`. 694 * 695 */ 696 typedef struct 697 { 698 otInstance *mInstance; ///< The OpenThread instance. 699 union 700 { 701 otChildInfo mChild; ///< The child neighbor info. 702 otNeighborInfo mRouter; ///< The router neighbor info. 703 } mInfo; 704 } otNeighborTableEntryInfo; 705 706 /** 707 * This function pointer is called to notify that there is a change in the neighbor table. 708 * 709 * @param[in] aEvent A event flag. 710 * @param[in] aEntryInfo A pointer to table entry info. 711 * 712 */ 713 typedef void (*otNeighborTableCallback)(otNeighborTableEvent aEvent, const otNeighborTableEntryInfo *aEntryInfo); 714 715 /** 716 * This function registers a neighbor table callback function. 717 * 718 * The provided callback (if non-NULL) will be invoked when there is a change in the neighbor table (e.g., a child or a 719 * router neighbor entry is being added/removed or an existing child's mode is changed). 720 * 721 * Subsequent calls to this method will overwrite the previous callback. Note that this callback in invoked while the 722 * neighbor/child table is being updated and always before the `otStateChangedCallback`. 723 * 724 * @param[in] aInstance A pointer to an OpenThread instance. 725 * @param[in] aCallback A pointer to callback handler function. 726 * 727 */ 728 void otThreadRegisterNeighborTableCallback(otInstance *aInstance, otNeighborTableCallback aCallback); 729 730 /** 731 * This function sets whether the device was commissioned using CCM. 732 * 733 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used by Thread Test Harness 734 * to indicate whether this device was commissioned using CCM. 735 * 736 * @param[in] aInstance A pointer to an OpenThread instance. 737 * @param[in] aEnabled TRUE if the device was commissioned using CCM, FALSE otherwise. 738 * 739 */ 740 void otThreadSetCcmEnabled(otInstance *aInstance, bool aEnabled); 741 742 /** 743 * This function sets whether the Security Policy TLV version-threshold for routing (VR field) is enabled. 744 * 745 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used by Thread Test Harness 746 * to indicate that thread protocol version check VR should be skipped. 747 * 748 * @param[in] aInstance A pointer to an OpenThread instance. 749 * @param[in] aEnabled TRUE to enable Security Policy TLV version-threshold for routing, FALSE otherwise. 750 * 751 */ 752 void otThreadSetThreadVersionCheckEnabled(otInstance *aInstance, bool aEnabled); 753 754 /** 755 * This function gets the range of router IDs that are allowed to assign to nodes within the thread network. 756 * 757 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used for test purpose. All the 758 * router IDs in the range [aMinRouterId, aMaxRouterId] are allowed. 759 * 760 * @param[in] aInstance A pointer to an OpenThread instance. 761 * @param[out] aMinRouterId The minimum router ID. 762 * @param[out] aMaxRouterId The maximum router ID. 763 * 764 * @sa otThreadSetRouterIdRange 765 * 766 */ 767 void otThreadGetRouterIdRange(otInstance *aInstance, uint8_t *aMinRouterId, uint8_t *aMaxRouterId); 768 769 /** 770 * This function sets the range of router IDs that are allowed to assign to nodes within the thread network. 771 * 772 * @note This API requires `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE`, and is only used for test purpose. All the 773 * router IDs in the range [aMinRouterId, aMaxRouterId] are allowed. 774 * 775 * @param[in] aInstance A pointer to an OpenThread instance. 776 * @param[in] aMinRouterId The minimum router ID. 777 * @param[in] aMaxRouterId The maximum router ID. 778 * 779 * @retval OT_ERROR_NONE Successfully set the range. 780 * @retval OT_ERROR_INVALID_ARGS aMinRouterId > aMaxRouterId, or the range is not covered by [0, 62]. 781 * 782 * @sa otThreadGetRouterIdRange 783 * 784 */ 785 otError otThreadSetRouterIdRange(otInstance *aInstance, uint8_t aMinRouterId, uint8_t aMaxRouterId); 786 /** 787 * @} 788 * 789 */ 790 791 #ifdef __cplusplus 792 } // extern "C" 793 #endif 794 795 #endif // OPENTHREAD_THREAD_FTD_H_ 796