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