1 /* 2 * Copyright (c) 2021-22, 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 Border Routing Manager API. 33 */ 34 35 #ifndef OPENTHREAD_BORDER_ROUTING_H_ 36 #define OPENTHREAD_BORDER_ROUTING_H_ 37 38 #include <openthread/error.h> 39 #include <openthread/ip6.h> 40 #include <openthread/netdata.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @addtogroup api-border-routing 48 * 49 * @brief 50 * This module includes definitions related to Border Routing Manager. 51 * 52 * 53 * @{ 54 * 55 * All the functions in this module require `OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE` to be enabled. 56 * 57 * Border Routing Manager handles bi-directional routing between Thread network and adjacent infrastructure link (AIL). 58 * 59 * It emits ICMRv6 ND Router Advertisement (RA) messages on AIL to advertise on-link and route prefixes. It also 60 * processes received RA messages from infrastructure and mirrors the discovered prefixes on the Thread Network Data to 61 * ensure devices on Thread mesh can reach AIL through the Border Router. 62 * 63 * Routing Manager manages the Off-Mesh Routable (OMR) prefix on the Thread Network data which configures Thread 64 * devices with a suitable Off-Mesh Routable IPv6 address. It announces the reachability of this prefix on AIL by 65 * including it in the emitted RA messages as an IPv6 Route Information Option (RIO). 66 * 67 * Routing Manager also monitors and adds on-link prefix on the infrastructure network. If a router on AIL is already 68 * providing RA messages containing an IPv6 Prefix Information Option (PIO) that enables IPv6 devices on the link to 69 * self-configure their own routable unicast IPv6 address, this address can be used by Thread devices to reach AIL. If 70 * Border Router finds no such RA message on AIL, it generates a ULA on-link prefix which it then advertises on AIL in 71 * the emitted RA messages. 72 */ 73 74 /** 75 * Represents an iterator to iterate through the Border Router's discovered prefix table. 76 * 77 * The fields in this type are opaque (intended for use by OpenThread core only) and therefore should not be 78 * accessed or used by caller. 79 * 80 * Before using an iterator, it MUST be initialized using `otBorderRoutingPrefixTableInitIterator()`. 81 */ 82 typedef struct otBorderRoutingPrefixTableIterator 83 { 84 const void *mPtr1; 85 const void *mPtr2; 86 uint32_t mData0; 87 uint32_t mData1; 88 uint8_t mData2; 89 uint8_t mData3; 90 } otBorderRoutingPrefixTableIterator; 91 92 /** 93 * Represents a discovered router on the infrastructure link. 94 * 95 * The `mIsPeerBr` field requires `OPENTHREAD_CONFIG_BORDER_ROUTING_TRACK_PEER_BR_INFO_ENABLE`. Routing Manager 96 * determines whether the router is a peer BR (connected to the same Thread mesh network) by comparing its advertised 97 * PIO/RIO prefixes with the entries in the Thread Network Data. While this method is generally effective, it may not 98 * be 100% accurate in all scenarios, so the `mIsPeerBr` flag should be used with caution. 99 */ 100 typedef struct otBorderRoutingRouterEntry 101 { 102 otIp6Address mAddress; ///< IPv6 address of the router. 103 uint32_t mMsecSinceLastUpdate; ///< Milliseconds since last update (any message rx) from this router. 104 uint32_t mAge; ///< The router's age in seconds (duration since its first discovery). 105 bool mManagedAddressConfigFlag : 1; ///< The router's Managed Address Config flag (`M` flag). 106 bool mOtherConfigFlag : 1; ///< The router's Other Config flag (`O` flag). 107 bool mSnacRouterFlag : 1; ///< The router's SNAC Router flag (`S` flag). 108 bool mIsLocalDevice : 1; ///< This router is the local device (this BR). 109 bool mIsReachable : 1; ///< This router is reachable. 110 bool mIsPeerBr : 1; ///< This router is (likely) a peer BR. 111 } otBorderRoutingRouterEntry; 112 113 /** 114 * Represents an entry from the discovered prefix table. 115 * 116 * The entries in the discovered table track the Prefix/Route Info Options in the received Router Advertisement messages 117 * from other routers on the infrastructure link. 118 */ 119 typedef struct otBorderRoutingPrefixTableEntry 120 { 121 otBorderRoutingRouterEntry mRouter; ///< Information about the router advertising this prefix. 122 otIp6Prefix mPrefix; ///< The discovered IPv6 prefix. 123 bool mIsOnLink; ///< Indicates whether the prefix is on-link or route prefix. 124 uint32_t mMsecSinceLastUpdate; ///< Milliseconds since last update of this prefix. 125 uint32_t mValidLifetime; ///< Valid lifetime of the prefix (in seconds). 126 otRoutePreference mRoutePreference; ///< Route preference when `mIsOnlink` is false. 127 uint32_t mPreferredLifetime; ///< Preferred lifetime of the on-link prefix when `mIsOnLink`. 128 } otBorderRoutingPrefixTableEntry; 129 130 /** 131 * Represents information about a peer Border Router found in the Network Data. 132 */ 133 typedef struct otBorderRoutingPeerBorderRouterEntry 134 { 135 uint16_t mRloc16; ///< The RLOC16 of BR. 136 uint32_t mAge; ///< Seconds since the BR appeared in the Network Data. 137 } otBorderRoutingPeerBorderRouterEntry; 138 139 /** 140 * Represents a group of data of platform-generated RA messages processed. 141 */ 142 typedef struct otPdProcessedRaInfo 143 { 144 uint32_t mNumPlatformRaReceived; ///< The number of platform generated RA handled by ProcessPlatformGeneratedRa. 145 uint32_t mNumPlatformPioProcessed; ///< The number of PIO processed for adding OMR prefixes. 146 uint32_t mLastPlatformRaMsec; ///< The timestamp of last processed RA message. 147 } otPdProcessedRaInfo; 148 149 /** 150 * Represents the state of Border Routing Manager. 151 */ 152 typedef enum 153 { 154 OT_BORDER_ROUTING_STATE_UNINITIALIZED, ///< Routing Manager is uninitialized. 155 OT_BORDER_ROUTING_STATE_DISABLED, ///< Routing Manager is initialized but disabled. 156 OT_BORDER_ROUTING_STATE_STOPPED, ///< Routing Manager in initialized and enabled but currently stopped. 157 OT_BORDER_ROUTING_STATE_RUNNING, ///< Routing Manager is initialized, enabled, and running. 158 } otBorderRoutingState; 159 160 /** 161 * This enumeration represents the state of DHCPv6 Prefix Delegation State. 162 */ 163 typedef enum 164 { 165 OT_BORDER_ROUTING_DHCP6_PD_STATE_DISABLED, ///< DHCPv6 PD is disabled on the border router. 166 OT_BORDER_ROUTING_DHCP6_PD_STATE_STOPPED, ///< DHCPv6 PD in enabled but won't try to request and publish a prefix. 167 OT_BORDER_ROUTING_DHCP6_PD_STATE_RUNNING, ///< DHCPv6 PD is enabled and will try to request and publish a prefix. 168 OT_BORDER_ROUTING_DHCP6_PD_STATE_IDLE, ///< DHCPv6 PD is idle; Higher-prf prefix published by other BRs. 169 } otBorderRoutingDhcp6PdState; 170 171 /** 172 * Initializes the Border Routing Manager on given infrastructure interface. 173 * 174 * @note This method MUST be called before any other otBorderRouting* APIs. 175 * @note This method can be re-called to change the infrastructure interface, but the Border Routing Manager should be 176 * disabled first, and re-enabled after. 177 * 178 * @param[in] aInstance A pointer to an OpenThread instance. 179 * @param[in] aInfraIfIndex The infrastructure interface index. 180 * @param[in] aInfraIfIsRunning A boolean that indicates whether the infrastructure 181 * interface is running. 182 * 183 * @retval OT_ERROR_NONE Successfully started the Border Routing Manager on given infrastructure. 184 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is in a state other than disabled or uninitialized. 185 * @retval OT_ERROR_INVALID_ARGS The index of the infrastructure interface is not valid. 186 * @retval OT_ERROR_FAILED Internal failure. Usually due to failure in generating random prefixes. 187 * 188 * @sa otPlatInfraIfStateChanged. 189 * @sa otBorderRoutingSetEnabled. 190 */ 191 otError otBorderRoutingInit(otInstance *aInstance, uint32_t aInfraIfIndex, bool aInfraIfIsRunning); 192 193 /** 194 * Enables or disables the Border Routing Manager. 195 * 196 * @note The Border Routing Manager is disabled by default. 197 * 198 * @param[in] aInstance A pointer to an OpenThread instance. 199 * @param[in] aEnabled A boolean to enable/disable the routing manager. 200 * 201 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 202 * @retval OT_ERROR_NONE Successfully enabled/disabled the Border Routing Manager. 203 */ 204 otError otBorderRoutingSetEnabled(otInstance *aInstance, bool aEnabled); 205 206 /** 207 * Gets the current state of Border Routing Manager. 208 * 209 * @param[in] aInstance A pointer to an OpenThread instance. 210 * 211 * @returns The current state of Border Routing Manager. 212 */ 213 otBorderRoutingState otBorderRoutingGetState(otInstance *aInstance); 214 215 /** 216 * Gets the current preference used when advertising Route Info Options (RIO) in Router Advertisement 217 * messages sent over the infrastructure link. 218 * 219 * The RIO preference is determined as follows: 220 * 221 * - If explicitly set by user by calling `otBorderRoutingSetRouteInfoOptionPreference()`, the given preference is 222 * used. 223 * - Otherwise, it is determined based on device's current role: Medium preference when in router/leader role and 224 * low preference when in child role. 225 * 226 * @returns The current Route Info Option preference. 227 */ 228 otRoutePreference otBorderRoutingGetRouteInfoOptionPreference(otInstance *aInstance); 229 230 /** 231 * Explicitly sets the preference to use when advertising Route Info Options (RIO) in Router 232 * Advertisement messages sent over the infrastructure link. 233 * 234 * After a call to this function, BR will use the given preference for all its advertised RIOs. The preference can be 235 * cleared by calling `otBorderRoutingClearRouteInfoOptionPreference()`. 236 * 237 * @param[in] aInstance A pointer to an OpenThread instance. 238 * @param[in] aPreference The route preference to use. 239 */ 240 void otBorderRoutingSetRouteInfoOptionPreference(otInstance *aInstance, otRoutePreference aPreference); 241 242 /** 243 * Clears a previously set preference value for advertised Route Info Options. 244 * 245 * After a call to this function, BR will use device's role to determine the RIO preference: Medium preference when 246 * in router/leader role and low preference when in child role. 247 * 248 * @param[in] aInstance A pointer to an OpenThread instance. 249 */ 250 void otBorderRoutingClearRouteInfoOptionPreference(otInstance *aInstance); 251 252 /** 253 * Sets additional options to append at the end of emitted Router Advertisement (RA) messages. 254 * 255 * The content of @p aOptions is copied internally, so it can be a temporary buffer (e.g., a stack allocated array). 256 * 257 * Subsequent calls to this function overwrite the previously set value. 258 * 259 * @param[in] aOptions A pointer to the encoded options. Can be `NULL` to clear. 260 * @param[in] aLength Number of bytes in @p aOptions. 261 * 262 * @retval OT_ERROR_NONE Successfully set the extra option bytes. 263 * @retval OT_ERROR_NO_BUFS Could not allocate buffer to save the buffer. 264 */ 265 otError otBorderRoutingSetExtraRouterAdvertOptions(otInstance *aInstance, const uint8_t *aOptions, uint16_t aLength); 266 267 /** 268 * Gets the current preference used for published routes in Network Data. 269 * 270 * The preference is determined as follows: 271 * 272 * - If explicitly set by user by calling `otBorderRoutingSetRoutePreference()`, the given preference is used. 273 * - Otherwise, it is determined automatically by `RoutingManager` based on the device's role and link quality. 274 * 275 * @param[in] aInstance A pointer to an OpenThread instance. 276 * 277 * @returns The current published route preference. 278 */ 279 otRoutePreference otBorderRoutingGetRoutePreference(otInstance *aInstance); 280 281 /** 282 * Explicitly sets the preference of published routes in Network Data. 283 * 284 * After a call to this function, BR will use the given preference. The preference can be cleared by calling 285 * `otBorderRoutingClearRoutePreference()`. 286 * 287 * @param[in] aInstance A pointer to an OpenThread instance. 288 * @param[in] aPreference The route preference to use. 289 */ 290 void otBorderRoutingSetRoutePreference(otInstance *aInstance, otRoutePreference aPreference); 291 292 /** 293 * Clears a previously set preference value for published routes in Network Data. 294 * 295 * After a call to this function, BR will determine the preference automatically based on the device's role and 296 * link quality (to the parent when acting as end-device). 297 * 298 * @param[in] aInstance A pointer to an OpenThread instance. 299 */ 300 void otBorderRoutingClearRoutePreference(otInstance *aInstance); 301 302 /** 303 * Gets the local Off-Mesh-Routable (OMR) Prefix, for example `fdfc:1ff5:1512:5622::/64`. 304 * 305 * An OMR Prefix is a randomly generated 64-bit prefix that's published in the 306 * Thread network if there isn't already an OMR prefix. This prefix can be reached 307 * from the local Wi-Fi or Ethernet network. 308 * 309 * Note: When DHCPv6 PD is enabled, the border router may publish the prefix from 310 * DHCPv6 PD. 311 * 312 * @param[in] aInstance A pointer to an OpenThread instance. 313 * @param[out] aPrefix A pointer to where the prefix will be output to. 314 * 315 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 316 * @retval OT_ERROR_NONE Successfully retrieved the OMR prefix. 317 * 318 * @sa otBorderRoutingGetPdOmrPrefix 319 */ 320 otError otBorderRoutingGetOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix); 321 322 /** 323 * Gets the DHCPv6 Prefix Delegation (PD) provided off-mesh-routable (OMR) prefix. 324 * 325 * Only mPrefix, mValidLifetime and mPreferredLifetime fields are used in the returned prefix info. 326 * 327 * `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE` must be enabled. 328 * 329 * @param[in] aInstance A pointer to an OpenThread instance. 330 * @param[out] aPrefixInfo A pointer to where the prefix info will be output to. 331 * 332 * @retval OT_ERROR_NONE Successfully retrieved the OMR prefix. 333 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 334 * @retval OT_ERROR_NOT_FOUND There are no valid PD prefix on this BR. 335 * 336 * @sa otBorderRoutingGetOmrPrefix 337 * @sa otPlatBorderRoutingProcessIcmp6Ra 338 */ 339 otError otBorderRoutingGetPdOmrPrefix(otInstance *aInstance, otBorderRoutingPrefixTableEntry *aPrefixInfo); 340 341 /** 342 * Gets the data of platform generated RA message processed.. 343 * 344 * `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE` must be enabled. 345 * 346 * @param[in] aInstance A pointer to an OpenThread instance. 347 * @param[out] aPrefixInfo A pointer to where the prefix info will be output to. 348 * 349 * @retval OT_ERROR_NONE Successfully retrieved the Info. 350 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 351 * @retval OT_ERROR_NOT_FOUND There are no valid Info on this BR. 352 */ 353 otError otBorderRoutingGetPdProcessedRaInfo(otInstance *aInstance, otPdProcessedRaInfo *aPdProcessedRaInfo); 354 355 /** 356 * Gets the currently favored Off-Mesh-Routable (OMR) Prefix. 357 * 358 * The favored OMR prefix can be discovered from Network Data or can be this device's local OMR prefix. 359 * 360 * @param[in] aInstance A pointer to an OpenThread instance. 361 * @param[out] aPrefix A pointer to output the favored OMR prefix. 362 * @param[out] aPreference A pointer to output the preference associated the favored prefix. 363 * 364 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not running yet. 365 * @retval OT_ERROR_NONE Successfully retrieved the favored OMR prefix. 366 */ 367 otError otBorderRoutingGetFavoredOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix, otRoutePreference *aPreference); 368 369 /** 370 * Gets the local On-Link Prefix for the adjacent infrastructure link. 371 * 372 * The local On-Link Prefix is a 64-bit prefix that's advertised on the infrastructure link if there isn't already a 373 * usable on-link prefix being advertised on the link. 374 * 375 * @param[in] aInstance A pointer to an OpenThread instance. 376 * @param[out] aPrefix A pointer to where the prefix will be output to. 377 * 378 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 379 * @retval OT_ERROR_NONE Successfully retrieved the local on-link prefix. 380 */ 381 otError otBorderRoutingGetOnLinkPrefix(otInstance *aInstance, otIp6Prefix *aPrefix); 382 383 /** 384 * Gets the currently favored On-Link Prefix. 385 * 386 * The favored prefix is either a discovered on-link prefix on the infrastructure link or the local on-link prefix. 387 * 388 * @param[in] aInstance A pointer to an OpenThread instance. 389 * @param[out] aPrefix A pointer to where the prefix will be output to. 390 * 391 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 392 * @retval OT_ERROR_NONE Successfully retrieved the favored on-link prefix. 393 */ 394 otError otBorderRoutingGetFavoredOnLinkPrefix(otInstance *aInstance, otIp6Prefix *aPrefix); 395 396 /** 397 * Gets the local NAT64 Prefix of the Border Router. 398 * 399 * NAT64 Prefix might not be advertised in the Thread network. 400 * 401 * `OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE` must be enabled. 402 * 403 * @param[in] aInstance A pointer to an OpenThread instance. 404 * @param[out] aPrefix A pointer to where the prefix will be output to. 405 * 406 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 407 * @retval OT_ERROR_NONE Successfully retrieved the NAT64 prefix. 408 */ 409 otError otBorderRoutingGetNat64Prefix(otInstance *aInstance, otIp6Prefix *aPrefix); 410 411 /** 412 * Gets the currently favored NAT64 prefix. 413 * 414 * The favored NAT64 prefix can be discovered from infrastructure link or can be this device's local NAT64 prefix. 415 * 416 * @param[in] aInstance A pointer to an OpenThread instance. 417 * @param[out] aPrefix A pointer to output the favored NAT64 prefix. 418 * @param[out] aPreference A pointer to output the preference associated the favored prefix. 419 * 420 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 421 * @retval OT_ERROR_NONE Successfully retrieved the favored NAT64 prefix. 422 */ 423 otError otBorderRoutingGetFavoredNat64Prefix(otInstance *aInstance, 424 otIp6Prefix *aPrefix, 425 otRoutePreference *aPreference); 426 427 /** 428 * Initializes an `otBorderRoutingPrefixTableIterator`. 429 * 430 * An iterator MUST be initialized before it is used. 431 * 432 * An iterator can be initialized again to restart from the beginning of the table. 433 * 434 * When iterating over entries in the table, to ensure the update times `mMsecSinceLastUpdate` of entries are 435 * consistent, they are given relative to the time the iterator was initialized. 436 * 437 * @param[in] aInstance The OpenThread instance. 438 * @param[out] aIterator A pointer to the iterator to initialize. 439 */ 440 void otBorderRoutingPrefixTableInitIterator(otInstance *aInstance, otBorderRoutingPrefixTableIterator *aIterator); 441 442 /** 443 * Iterates over the entries in the Border Router's discovered prefix table. 444 * 445 * Prefix entries associated with the same discovered router on an infrastructure link are guaranteed to be grouped 446 * together (retrieved back-to-back). 447 * 448 * @param[in] aInstance The OpenThread instance. 449 * @param[in,out] aIterator A pointer to the iterator. 450 * @param[out] aEntry A pointer to the entry to populate. 451 * 452 * @retval OT_ERROR_NONE Iterated to the next entry, @p aEntry and @p aIterator are updated. 453 * @retval OT_ERROR_NOT_FOUND No more entries in the table. 454 */ 455 otError otBorderRoutingGetNextPrefixTableEntry(otInstance *aInstance, 456 otBorderRoutingPrefixTableIterator *aIterator, 457 otBorderRoutingPrefixTableEntry *aEntry); 458 459 /** 460 * Iterates over the discovered router entries on the infrastructure link. 461 * 462 * @param[in] aInstance The OpenThread instance. 463 * @param[in,out] aIterator A pointer to the iterator. 464 * @param[out] aEntry A pointer to the entry to populate. 465 * 466 * @retval OT_ERROR_NONE Iterated to the next router, @p aEntry and @p aIterator are updated. 467 * @retval OT_ERROR_NOT_FOUND No more router entries. 468 */ 469 otError otBorderRoutingGetNextRouterEntry(otInstance *aInstance, 470 otBorderRoutingPrefixTableIterator *aIterator, 471 otBorderRoutingRouterEntry *aEntry); 472 473 /** 474 * Iterates over the peer BRs found in the Network Data. 475 * 476 * Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_TRACK_PEER_BR_INFO_ENABLE`. 477 * 478 * Peer BRs are other devices within the Thread mesh that provide external IP connectivity. A device is considered 479 * to provide external IP connectivity if at least one of the following conditions is met regarding its Network Data 480 * entries: 481 * 482 * - It has added at least one external route entry. 483 * - It has added at least one prefix entry with both the default-route and on-mesh flags set. 484 * - It has added at least one domain prefix (with both the domain and on-mesh flags set). 485 * 486 * The list of peer BRs specifically excludes the current device, even if it is itself acting as a BR. 487 * 488 * @param[in] aInstance The OpenThread instance. 489 * @param[in,out] aIterator A pointer to the iterator. 490 * @param[out] aEntry A pointer to the entry to populate. 491 * 492 * @retval OT_ERROR_NONE Iterated to the next entry, @p aEntry and @p aIterator are updated. 493 * @retval OT_ERROR_NOT_FOUND No more entries. 494 */ 495 otError otBorderRoutingGetNextPeerBrEntry(otInstance *aInstance, 496 otBorderRoutingPrefixTableIterator *aIterator, 497 otBorderRoutingPeerBorderRouterEntry *aEntry); 498 499 /** 500 * Returns the number of peer BRs found in the Network Data. 501 * 502 * Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_TRACK_PEER_BR_INFO_ENABLE`. 503 * 504 * Peer BRs are other devices within the Thread mesh that provide external IP connectivity. A device is considered 505 * to provide external IP connectivity if at least one of the following conditions is met regarding its Network Data 506 * entries: 507 * 508 * - It has added at least one external route entry. 509 * - It has added at least one prefix entry with both the default-route and on-mesh flags set. 510 * - It has added at least one domain prefix (with both the domain and on-mesh flags set). 511 * 512 * The list of peer BRs specifically excludes the current device, even if it is itself acting as a BR. 513 * 514 * @param[in] aInstance The OpenThread instance. 515 * @param[out] aMinAge Pointer to an `uint32_t` to return the minimum age among all peer BRs. 516 * Can be NULL if the caller does not need this information. 517 * Age is represented as seconds since appearance of the BR entry in the Network Data. 518 * 519 * @returns The number of peer BRs. 520 */ 521 uint16_t otBorderRoutingCountPeerBrs(otInstance *aInstance, uint32_t *aMinAge); 522 523 /** 524 * Enables / Disables DHCPv6 Prefix Delegation. 525 * 526 * `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE` must be enabled. 527 * 528 * @param[in] aInstance A pointer to an OpenThread instance. 529 * @param[in] aEnabled Whether to accept platform generated RA messages. 530 */ 531 void otBorderRoutingDhcp6PdSetEnabled(otInstance *aInstance, bool aEnabled); 532 533 /** 534 * Gets the current state of DHCPv6 Prefix Delegation. 535 * 536 * Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE` to be enabled. 537 * 538 * @param[in] aInstance A pointer to an OpenThread instance. 539 * 540 * @returns The current state of DHCPv6 Prefix Delegation. 541 */ 542 otBorderRoutingDhcp6PdState otBorderRoutingDhcp6PdGetState(otInstance *aInstance); 543 544 /** 545 * When the state of a DHCPv6 Prefix Delegation (PD) on the Thread interface changes, this callback notifies processes 546 * in the OS of this changed state. 547 * 548 * @param[in] aState The state of DHCPv6 Prefix Delegation State. 549 * @param[in] aContext A pointer to arbitrary context information. 550 */ 551 typedef void (*otBorderRoutingRequestDhcp6PdCallback)(otBorderRoutingDhcp6PdState aState, void *aContext); 552 553 /** 554 * Sets the callback whenever the DHCPv6 PD state changes on the Thread interface. 555 * 556 * Subsequent calls to this function replace the previously set callback. 557 * 558 * @param[in] aInstance A pointer to an OpenThread instance. 559 * @param[in] aCallback A pointer to a function that is called whenever the DHCPv6 PD state changes. 560 * @param[in] aContext A pointer to arbitrary context information. 561 */ 562 void otBorderRoutingDhcp6PdSetRequestCallback(otInstance *aInstance, 563 otBorderRoutingRequestDhcp6PdCallback aCallback, 564 void *aContext); 565 566 /** 567 * Sets the local on-link prefix. 568 * 569 * Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_TESTING_API_ENABLE`. 570 * 571 * This is intended for testing only and using it will make the BR non-compliant with the Thread Specification. 572 * 573 * @param[in] aPrefix The on-link prefix to use. 574 */ 575 void otBorderRoutingSetOnLinkPrefix(otInstance *aInstance, const otIp6Prefix *aPrefix); 576 577 /** 578 * @} 579 */ 580 581 #ifdef __cplusplus 582 } // extern "C" 583 #endif 584 585 #endif // OPENTHREAD_BORDER_ROUTING_H_ 586