1 /* 2 * Copyright (c) 2019, 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 Backbone Router API (for Thread 1.2 FTD with 33 * `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE`). 34 */ 35 36 #ifndef OPENTHREAD_BACKBONE_ROUTER_FTD_H_ 37 #define OPENTHREAD_BACKBONE_ROUTER_FTD_H_ 38 39 #include <openthread/backbone_router.h> 40 #include <openthread/ip6.h> 41 #include <openthread/netdata.h> 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * @addtogroup api-backbone-router 49 * 50 * @{ 51 */ 52 53 /** 54 * Represents the Backbone Router Status. 55 */ 56 typedef enum 57 { 58 OT_BACKBONE_ROUTER_STATE_DISABLED = 0, ///< Backbone function is disabled. 59 OT_BACKBONE_ROUTER_STATE_SECONDARY = 1, ///< Secondary Backbone Router. 60 OT_BACKBONE_ROUTER_STATE_PRIMARY = 2, ///< The Primary Backbone Router. 61 } otBackboneRouterState; 62 63 /** 64 * Enables or disables Backbone functionality. 65 * 66 * If enabled, a Server Data Request message `SRV_DATA.ntf` is triggered for the attached 67 * device if there is no Backbone Router Service in the Thread Network Data. 68 * 69 * If disabled, `SRV_DATA.ntf` is triggered if the Backbone Router is in the Primary state. 70 * 71 * Available when `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE` is enabled. 72 * 73 * @param[in] aInstance A pointer to an OpenThread instance. 74 * @param[in] aEnable TRUE to enable Backbone functionality, FALSE otherwise. 75 * 76 * @sa otBackboneRouterGetState 77 * @sa otBackboneRouterGetConfig 78 * @sa otBackboneRouterSetConfig 79 * @sa otBackboneRouterRegister 80 */ 81 void otBackboneRouterSetEnabled(otInstance *aInstance, bool aEnable); 82 83 /** 84 * Gets the Backbone Router #otBackboneRouterState. 85 * 86 * @param[in] aInstance A pointer to an OpenThread instance. 87 * 88 * @retval OT_BACKBONE_ROUTER_STATE_DISABLED Backbone functionality is disabled. 89 * @retval OT_BACKBONE_ROUTER_STATE_SECONDARY Secondary Backbone Router. 90 * @retval OT_BACKBONE_ROUTER_STATE_PRIMARY The Primary Backbone Router. 91 * 92 * @sa otBackboneRouterSetEnabled 93 * @sa otBackboneRouterGetConfig 94 * @sa otBackboneRouterSetConfig 95 * @sa otBackboneRouterRegister 96 */ 97 otBackboneRouterState otBackboneRouterGetState(otInstance *aInstance); 98 99 /** 100 * Gets the local Backbone Router configuration. 101 * 102 * Available when `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE` is enabled. 103 * 104 * @param[in] aInstance A pointer to an OpenThread instance. 105 * @param[out] aConfig A pointer where to put local Backbone Router configuration. 106 * 107 * 108 * @sa otBackboneRouterSetEnabled 109 * @sa otBackboneRouterGetState 110 * @sa otBackboneRouterSetConfig 111 * @sa otBackboneRouterRegister 112 */ 113 void otBackboneRouterGetConfig(otInstance *aInstance, otBackboneRouterConfig *aConfig); 114 115 /** 116 * Sets the local Backbone Router configuration #otBackboneRouterConfig. 117 * 118 * A Server Data Request message `SRV_DATA.ntf` is initiated automatically if BBR Dataset changes for Primary 119 * Backbone Router. 120 * 121 * Available when `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE` is enabled. 122 * 123 * @param[in] aInstance A pointer to an OpenThread instance. 124 * @param[in] aConfig A pointer to the Backbone Router configuration to take effect. 125 * 126 * @retval OT_ERROR_NONE Successfully updated configuration. 127 * @retval OT_ERROR_INVALID_ARGS The configuration in @p aConfig is invalid. 128 * 129 * @sa otBackboneRouterSetEnabled 130 * @sa otBackboneRouterGetState 131 * @sa otBackboneRouterGetConfig 132 * @sa otBackboneRouterRegister 133 */ 134 otError otBackboneRouterSetConfig(otInstance *aInstance, const otBackboneRouterConfig *aConfig); 135 136 /** 137 * Explicitly registers local Backbone Router configuration. 138 * 139 * A Server Data Request message `SRV_DATA.ntf` is triggered for the attached device. 140 * 141 * Available when `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE` is enabled. 142 * 143 * @param[in] aInstance A pointer to an OpenThread instance. 144 * 145 * @retval OT_ERROR_NO_BUFS Insufficient space to add the Backbone Router service. 146 * @retval OT_ERROR_NONE Successfully queued a Server Data Request message for delivery. 147 * 148 * @sa otBackboneRouterSetEnabled 149 * @sa otBackboneRouterGetState 150 * @sa otBackboneRouterGetConfig 151 * @sa otBackboneRouterSetConfig 152 */ 153 otError otBackboneRouterRegister(otInstance *aInstance); 154 155 /** 156 * Returns the Backbone Router registration jitter value. 157 * 158 * @returns The Backbone Router registration jitter value. 159 * 160 * @sa otBackboneRouterSetRegistrationJitter 161 */ 162 uint8_t otBackboneRouterGetRegistrationJitter(otInstance *aInstance); 163 164 /** 165 * Sets the Backbone Router registration jitter value. 166 * 167 * @param[in] aJitter the Backbone Router registration jitter value to set. 168 * 169 * @sa otBackboneRouterGetRegistrationJitter 170 */ 171 void otBackboneRouterSetRegistrationJitter(otInstance *aInstance, uint8_t aJitter); 172 173 /** 174 * Gets the local Domain Prefix configuration. 175 * 176 * @param[in] aInstance A pointer to an OpenThread instance. 177 * @param[out] aConfig A pointer to the Domain Prefix configuration. 178 * 179 * @retval OT_ERROR_NONE Successfully got the Domain Prefix configuration. 180 * @retval OT_ERROR_NOT_FOUND No Domain Prefix was configured. 181 */ 182 otError otBackboneRouterGetDomainPrefix(otInstance *aInstance, otBorderRouterConfig *aConfig); 183 184 /** 185 * Configures response status for next DUA registration. 186 * 187 * Note: available only when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 188 * Only used for test and certification. 189 * 190 * TODO: (DUA) support coap error code and corresponding process for certification purpose. 191 * 192 * @param[in] aInstance A pointer to an OpenThread instance. 193 * @param[in] aMlIid A pointer to the Mesh Local IID. If NULL, respond with @p aStatus for any 194 * coming DUA.req, otherwise only respond the one with matching @p aMlIid. 195 * @param[in] aStatus The status to respond. 196 */ 197 void otBackboneRouterConfigNextDuaRegistrationResponse(otInstance *aInstance, 198 const otIp6InterfaceIdentifier *aMlIid, 199 uint8_t aStatus); 200 201 /** 202 * Configures the response status for the next Multicast Listener Registration. 203 * 204 * Available when `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE`, 205 * `OPENTHREAD_CONFIG_BACKBONE_ROUTER_MULTICAST_ROUTING_ENABLE`, and 206 * `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` are enabled. 207 * 208 * @param[in] aInstance A pointer to an OpenThread instance. 209 * @param[in] aStatus The status to respond. 210 */ 211 void otBackboneRouterConfigNextMulticastListenerRegistrationResponse(otInstance *aInstance, uint8_t aStatus); 212 213 /** 214 * Represents the Multicast Listener events. 215 */ 216 typedef enum 217 { 218 OT_BACKBONE_ROUTER_MULTICAST_LISTENER_ADDED = 0, ///< Multicast Listener was added. 219 OT_BACKBONE_ROUTER_MULTICAST_LISTENER_REMOVED = 1, ///< Multicast Listener was removed or expired. 220 } otBackboneRouterMulticastListenerEvent; 221 222 /** 223 * Pointer is called whenever the Multicast Listeners change. 224 * 225 * @param[in] aContext The user context pointer. 226 * @param[in] aEvent The Multicast Listener event. 227 * @param[in] aAddress The IPv6 multicast address of the Multicast Listener. 228 */ 229 typedef void (*otBackboneRouterMulticastListenerCallback)(void *aContext, 230 otBackboneRouterMulticastListenerEvent aEvent, 231 const otIp6Address *aAddress); 232 233 /** 234 * Sets the Backbone Router Multicast Listener callback. 235 * 236 * @param[in] aInstance A pointer to an OpenThread instance. 237 * @param[in] aCallback A pointer to the Multicast Listener callback. 238 * @param[in] aContext A user context pointer. 239 */ 240 void otBackboneRouterSetMulticastListenerCallback(otInstance *aInstance, 241 otBackboneRouterMulticastListenerCallback aCallback, 242 void *aContext); 243 244 /** 245 * Clears the Multicast Listeners. 246 * 247 * Available when `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE`, 248 * `OPENTHREAD_CONFIG_BACKBONE_ROUTER_MULTICAST_ROUTING_ENABLE`, and 249 * `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` are enabled. 250 * 251 * @param[in] aInstance A pointer to an OpenThread instance. 252 * 253 * @sa otBackboneRouterMulticastListenerAdd 254 * @sa otBackboneRouterMulticastListenerGetNext 255 */ 256 void otBackboneRouterMulticastListenerClear(otInstance *aInstance); 257 258 /** 259 * Adds a Multicast Listener with a timeout value, in seconds. 260 * 261 * Pass `0` to use the default MLR timeout. 262 * 263 * Available when `OPENTHREAD_CONFIG_BACKBONE_ROUTER_ENABLE`, 264 * `OPENTHREAD_CONFIG_BACKBONE_ROUTER_MULTICAST_ROUTING_ENABLE`, and 265 * `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` are enabled. 266 * 267 * @param[in] aInstance A pointer to an OpenThread instance. 268 * @param[in] aAddress The Multicast Listener address. 269 * @param[in] aTimeout The timeout (in seconds) of the Multicast Listener, or 0 to use the default MLR timeout. 270 * 271 * @retval OT_ERROR_NONE If the Multicast Listener was successfully added. 272 * @retval OT_ERROR_INVALID_ARGS If the Multicast Listener address was invalid. 273 * @retval OT_ERROR_NO_BUFS No space available to save the Multicast Listener. 274 * 275 * @sa otBackboneRouterMulticastListenerClear 276 * @sa otBackboneRouterMulticastListenerGetNext 277 */ 278 otError otBackboneRouterMulticastListenerAdd(otInstance *aInstance, const otIp6Address *aAddress, uint32_t aTimeout); 279 280 #define OT_BACKBONE_ROUTER_MULTICAST_LISTENER_ITERATOR_INIT \ 281 0 ///< Initializer for otBackboneRouterMulticastListenerIterator 282 283 typedef uint16_t otBackboneRouterMulticastListenerIterator; ///< Used to iterate through Multicast Listeners. 284 285 /** 286 * Represents a Backbone Router Multicast Listener info. 287 */ 288 typedef struct otBackboneRouterMulticastListenerInfo 289 { 290 otIp6Address mAddress; // Multicast Listener address. 291 uint32_t mTimeout; // Timeout (in seconds). 292 } otBackboneRouterMulticastListenerInfo; 293 294 /** 295 * Gets the next Multicast Listener info (using an iterator). 296 * 297 * @param[in] aInstance A pointer to an OpenThread instance. 298 * @param[in,out] aIterator A pointer to the iterator. On success the iterator will be updated to point to next 299 * Multicast Listener. To get the first entry the iterator should be set to 300 * OT_BACKBONE_ROUTER_MULTICAST_LISTENER_ITERATOR_INIT. 301 * @param[out] aListenerInfo A pointer to an `otBackboneRouterMulticastListenerInfo` where information of next 302 * Multicast Listener is placed (on success). 303 * 304 * @retval OT_ERROR_NONE Successfully found the next Multicast Listener info (@p aListenerInfo was successfully 305 * updated). 306 * @retval OT_ERROR_NOT_FOUND No subsequent Multicast Listener info was found. 307 * 308 * @sa otBackboneRouterMulticastListenerClear 309 * @sa otBackboneRouterMulticastListenerAdd 310 */ 311 otError otBackboneRouterMulticastListenerGetNext(otInstance *aInstance, 312 otBackboneRouterMulticastListenerIterator *aIterator, 313 otBackboneRouterMulticastListenerInfo *aListenerInfo); 314 315 /** 316 * Represents the ND Proxy events. 317 */ 318 typedef enum 319 { 320 OT_BACKBONE_ROUTER_NDPROXY_ADDED = 0, ///< ND Proxy was added. 321 OT_BACKBONE_ROUTER_NDPROXY_REMOVED = 1, ///< ND Proxy was removed. 322 OT_BACKBONE_ROUTER_NDPROXY_RENEWED = 2, ///< ND Proxy was renewed. 323 OT_BACKBONE_ROUTER_NDPROXY_CLEARED = 3, ///< All ND Proxies were cleared. 324 } otBackboneRouterNdProxyEvent; 325 326 /** 327 * Pointer is called whenever the Nd Proxy changed. 328 * 329 * @param[in] aContext The user context pointer. 330 * @param[in] aEvent The ND Proxy event. 331 * @param[in] aDua The Domain Unicast Address of the ND Proxy, or `nullptr` if @p aEvent is 332 * `OT_BACKBONE_ROUTER_NDPROXY_CLEARED`. 333 */ 334 typedef void (*otBackboneRouterNdProxyCallback)(void *aContext, 335 otBackboneRouterNdProxyEvent aEvent, 336 const otIp6Address *aDua); 337 338 /** 339 * Sets the Backbone Router ND Proxy callback. 340 * 341 * @param[in] aInstance A pointer to an OpenThread instance. 342 * @param[in] aCallback A pointer to the ND Proxy callback. 343 * @param[in] aContext A user context pointer. 344 */ 345 void otBackboneRouterSetNdProxyCallback(otInstance *aInstance, 346 otBackboneRouterNdProxyCallback aCallback, 347 void *aContext); 348 349 /** 350 * Represents the Backbone Router ND Proxy info. 351 */ 352 typedef struct otBackboneRouterNdProxyInfo 353 { 354 otIp6InterfaceIdentifier *mMeshLocalIid; ///< Mesh-local IID 355 uint32_t mTimeSinceLastTransaction; ///< Time since last transaction (Seconds) 356 uint16_t mRloc16; ///< RLOC16 357 } otBackboneRouterNdProxyInfo; 358 359 /** 360 * Gets the Backbone Router ND Proxy info. 361 * 362 * @param[in] aInstance A pointer to an OpenThread instance. 363 * @param[in] aDua The Domain Unicast Address. 364 * @param[out] aNdProxyInfo A pointer to the ND Proxy info. 365 * 366 * @retval OT_ERROR_NONE Successfully got the ND Proxy info. 367 * @retval OT_ERROR_NOT_FOUND Failed to find the Domain Unicast Address in the ND Proxy table. 368 */ 369 otError otBackboneRouterGetNdProxyInfo(otInstance *aInstance, 370 const otIp6Address *aDua, 371 otBackboneRouterNdProxyInfo *aNdProxyInfo); 372 373 /** 374 * Represents the Domain Prefix events. 375 */ 376 typedef enum 377 { 378 OT_BACKBONE_ROUTER_DOMAIN_PREFIX_ADDED = 0, ///< Domain Prefix was added. 379 OT_BACKBONE_ROUTER_DOMAIN_PREFIX_REMOVED = 1, ///< Domain Prefix was removed. 380 OT_BACKBONE_ROUTER_DOMAIN_PREFIX_CHANGED = 2, ///< Domain Prefix was changed. 381 } otBackboneRouterDomainPrefixEvent; 382 383 /** 384 * Pointer is called whenever the Domain Prefix changed. 385 * 386 * @param[in] aContext The user context pointer. 387 * @param[in] aEvent The Domain Prefix event. 388 * @param[in] aDomainPrefix The new Domain Prefix if added or changed, nullptr otherwise. 389 */ 390 typedef void (*otBackboneRouterDomainPrefixCallback)(void *aContext, 391 otBackboneRouterDomainPrefixEvent aEvent, 392 const otIp6Prefix *aDomainPrefix); 393 /** 394 * Sets the Backbone Router Domain Prefix callback. 395 * 396 * @param[in] aInstance A pointer to an OpenThread instance. 397 * @param[in] aCallback A pointer to the Domain Prefix callback. 398 * @param[in] aContext A user context pointer. 399 */ 400 void otBackboneRouterSetDomainPrefixCallback(otInstance *aInstance, 401 otBackboneRouterDomainPrefixCallback aCallback, 402 void *aContext); 403 404 /** 405 * @} 406 */ 407 408 #ifdef __cplusplus 409 } // extern "C" 410 #endif 411 412 #endif // OPENTHREAD_BACKBONE_ROUTER_FTD_H_ 413
