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 /** 76 * This structure represents an iterator to iterate through the Border Router's discovered prefix table. 77 * 78 * The fields in this type are opaque (intended for use by OpenThread core only) and therefore should not be 79 * accessed or used by caller. 80 * 81 * Before using an iterator, it MUST be initialized using `otBorderRoutingPrefixTableInitIterator()`. 82 * 83 */ 84 typedef struct otBorderRoutingPrefixTableIterator 85 { 86 const void *mPtr1; 87 const void *mPtr2; 88 uint32_t mData32; 89 } otBorderRoutingPrefixTableIterator; 90 91 /** 92 * This structure represents an entry from the discovered prefix table. 93 * 94 * The entries in the discovered table track the Prefix/Route Info Options in the received Router Advertisement messages 95 * from other routers on infrastructure link. 96 * 97 */ 98 typedef struct otBorderRoutingPrefixTableEntry 99 { 100 otIp6Address mRouterAddress; ///< IPv6 address of the router. 101 otIp6Prefix mPrefix; ///< The discovered IPv6 prefix. 102 bool mIsOnLink; ///< Indicates whether the prefix is on-link or route prefix. 103 uint32_t mMsecSinceLastUpdate; ///< Milliseconds since last update of this prefix. 104 uint32_t mValidLifetime; ///< Valid lifetime of the prefix (in seconds). 105 otRoutePreference mRoutePreference; ///< Route preference when `mIsOnlink` is false. 106 uint32_t mPreferredLifetime; ///< Preferred lifetime of the on-link prefix when `mIsOnLink` is true. 107 } otBorderRoutingPrefixTableEntry; 108 109 /** 110 * This method initializes the Border Routing Manager on given infrastructure interface. 111 * 112 * @note This method MUST be called before any other otBorderRouting* APIs. 113 * 114 * @param[in] aInstance A pointer to an OpenThread instance. 115 * @param[in] aInfraIfIndex The infrastructure interface index. 116 * @param[in] aInfraIfIsRunning A boolean that indicates whether the infrastructure 117 * interface is running. 118 * 119 * @retval OT_ERROR_NONE Successfully started the Border Routing Manager on given infrastructure. 120 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager has already been initialized. 121 * @retval OT_ERROR_INVALID_ARGS The index of the infrastructure interface is not valid. 122 * @retval OT_ERROR_FAILED Internal failure. Usually due to failure in generating random prefixes. 123 * 124 * @sa otPlatInfraIfStateChanged. 125 * 126 */ 127 otError otBorderRoutingInit(otInstance *aInstance, uint32_t aInfraIfIndex, bool aInfraIfIsRunning); 128 129 /** 130 * Enables or disables the Border Routing Manager. 131 * 132 * @note The Border Routing Manager is disabled by default. 133 * 134 * @param[in] aInstance A pointer to an OpenThread instance. 135 * @param[in] aEnabled A boolean to enable/disable the routing manager. 136 * 137 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 138 * @retval OT_ERROR_NONE Successfully enabled/disabled the Border Routing Manager. 139 * 140 */ 141 otError otBorderRoutingSetEnabled(otInstance *aInstance, bool aEnabled); 142 143 /** 144 * This function gets the preference used when advertising Route Info Options (e.g., for discovered OMR prefixes) in 145 * Router Advertisement messages sent over the infrastructure link. 146 * 147 * @param[in] aInstance A pointer to an OpenThread instance. 148 * 149 * @returns The OMR prefix advertisement preference. 150 * 151 */ 152 otRoutePreference otBorderRoutingGetRouteInfoOptionPreference(otInstance *aInstance); 153 154 /** 155 * This function sets the preference to use when advertising Route Info Options in Router Advertisement messages sent 156 * over the infrastructure link, for example for discovered OMR prefixes. 157 * 158 * By default BR will use `medium` preference level, but this function allows the default value to be changed. As an 159 * example, it can be set to `low` preference in the case where device is a temporary BR (a mobile BR or a 160 * battery-powered BR) to indicate that other BRs (if any) should be preferred over this BR on the infrastructure link. 161 * 162 * @param[in] aInstance A pointer to an OpenThread instance. 163 * @param[in] aPreference The route preference to use. 164 * 165 */ 166 void otBorderRoutingSetRouteInfoOptionPreference(otInstance *aInstance, otRoutePreference aPreference); 167 168 /** 169 * Gets the local Off-Mesh-Routable (OMR) Prefix, for example `fdfc:1ff5:1512:5622::/64`. 170 * 171 * An OMR Prefix is a randomly generated 64-bit prefix that's published in the 172 * Thread network if there isn't already an OMR prefix. This prefix can be reached 173 * from the local Wi-Fi or Ethernet network. 174 * 175 * @param[in] aInstance A pointer to an OpenThread instance. 176 * @param[out] aPrefix A pointer to where the prefix will be output to. 177 * 178 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 179 * @retval OT_ERROR_NONE Successfully retrieved the OMR prefix. 180 * 181 */ 182 otError otBorderRoutingGetOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix); 183 184 /** 185 * Gets the currently favored Off-Mesh-Routable (OMR) Prefix. 186 * 187 * The favored OMR prefix can be discovered from Network Data or can be this device's local OMR prefix. 188 * 189 * @param[in] aInstance A pointer to an OpenThread instance. 190 * @param[out] aPrefix A pointer to output the favored OMR prefix. 191 * @param[out] aPreference A pointer to output the preference associated the favored prefix. 192 * 193 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 194 * @retval OT_ERROR_NONE Successfully retrieved the favored OMR prefix. 195 * 196 */ 197 otError otBorderRoutingGetFavoredOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix, otRoutePreference *aPreference); 198 199 /** 200 * Gets the On-Link Prefix for the adjacent infrastructure link, for example `fd41:2650:a6f5:0::/64`. 201 * 202 * An On-Link Prefix is a 64-bit prefix that's advertised on the infrastructure link if there isn't already a usable 203 * on-link prefix being advertised on the link. 204 * 205 * @param[in] aInstance A pointer to an OpenThread instance. 206 * @param[out] aPrefix A pointer to where the prefix will be output to. 207 * 208 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 209 * @retval OT_ERROR_NONE Successfully retrieved the on-link prefix. 210 * 211 */ 212 otError otBorderRoutingGetOnLinkPrefix(otInstance *aInstance, otIp6Prefix *aPrefix); 213 214 /** 215 * Gets the local NAT64 Prefix of the Border Router. 216 * 217 * NAT64 Prefix might not be advertised in the Thread network. 218 * 219 * `OPENTHREAD_CONFIG_BORDER_ROUTING_NAT64_ENABLE` must be enabled. 220 * 221 * @param[in] aInstance A pointer to an OpenThread instance. 222 * @param[out] aPrefix A pointer to where the prefix will be output to. 223 * 224 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 225 * @retval OT_ERROR_NONE Successfully retrieved the NAT64 prefix. 226 * 227 */ 228 otError otBorderRoutingGetNat64Prefix(otInstance *aInstance, otIp6Prefix *aPrefix); 229 230 /** 231 * This function initializes an `otBorderRoutingPrefixTableIterator`. 232 * 233 * An iterator MUST be initialized before it is used. 234 * 235 * An iterator can be initialized again to restart from the beginning of the table. 236 * 237 * When iterating over entries in the table, to ensure the update times `mMsecSinceLastUpdate` of entries are 238 * consistent, they are given relative to the time the iterator was initialized. 239 * 240 * @param[in] aInstance The OpenThread instance. 241 * @param[out] aIterator A pointer to the iterator to initialize. 242 * 243 */ 244 void otBorderRoutingPrefixTableInitIterator(otInstance *aInstance, otBorderRoutingPrefixTableIterator *aIterator); 245 246 /** 247 * This function iterates over the entries in the Border Router's discovered prefix table. 248 * 249 * @param[in] aInstance The OpenThread instance. 250 * @param[in,out] aIterator A pointer to the iterator. 251 * @param[out] aEntry A pointer to the entry to populate. 252 * 253 * @retval OT_ERROR_NONE Iterated to the next entry, @p aEntry and @p aIterator are updated. 254 * @retval OT_ERROR_NOT_FOUND No more entries in the table. 255 * 256 */ 257 otError otBorderRoutingGetNextPrefixTableEntry(otInstance * aInstance, 258 otBorderRoutingPrefixTableIterator *aIterator, 259 otBorderRoutingPrefixTableEntry * aEntry); 260 261 /** 262 * @} 263 * 264 */ 265 266 #ifdef __cplusplus 267 } // extern "C" 268 #endif 269 270 #endif // OPENTHREAD_BORDER_ROUTING_H_ 271