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