1 /* 2 * Copyright (c) 2016-2017, 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 Router API. 33 */ 34 35 #ifndef OPENTHREAD_BORDER_ROUTER_H_ 36 #define OPENTHREAD_BORDER_ROUTER_H_ 37 38 #include <openthread/border_routing.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-router 48 * 49 * @brief 50 * This module includes functions to manage local network data with the OpenThread Border Router. 51 * 52 * @{ 53 */ 54 55 /** 56 * Provides a full or stable copy of the local Thread Network Data. 57 * 58 * @param[in] aInstance A pointer to an OpenThread instance. 59 * @param[in] aStable TRUE when copying the stable version, FALSE when copying the full version. 60 * @param[out] aData A pointer to the data buffer. 61 * @param[in,out] aDataLength On entry, size of the data buffer pointed to by @p aData. 62 * On exit, number of copied bytes. 63 */ 64 otError otBorderRouterGetNetData(otInstance *aInstance, bool aStable, uint8_t *aData, uint8_t *aDataLength); 65 66 /** 67 * Add a border router configuration to the local network data. 68 * 69 * @param[in] aInstance A pointer to an OpenThread instance. 70 * @param[in] aConfig A pointer to the border router configuration. 71 * 72 * @retval OT_ERROR_NONE Successfully added the configuration to the local network data. 73 * @retval OT_ERROR_INVALID_ARGS One or more configuration parameters were invalid. 74 * @retval OT_ERROR_NO_BUFS Not enough room is available to add the configuration to the local network data. 75 * 76 * @sa otBorderRouterRemoveOnMeshPrefix 77 * @sa otBorderRouterRegister 78 */ 79 otError otBorderRouterAddOnMeshPrefix(otInstance *aInstance, const otBorderRouterConfig *aConfig); 80 81 /** 82 * Remove a border router configuration from the local network data. 83 * 84 * @param[in] aInstance A pointer to an OpenThread instance. 85 * @param[in] aPrefix A pointer to an IPv6 prefix. 86 * 87 * @retval OT_ERROR_NONE Successfully removed the configuration from the local network data. 88 * @retval OT_ERROR_NOT_FOUND Could not find the Border Router entry. 89 * 90 * @sa otBorderRouterAddOnMeshPrefix 91 * @sa otBorderRouterRegister 92 */ 93 otError otBorderRouterRemoveOnMeshPrefix(otInstance *aInstance, const otIp6Prefix *aPrefix); 94 95 /** 96 * Gets the next On Mesh Prefix in the local Network Data. 97 * 98 * @param[in] aInstance A pointer to an OpenThread instance. 99 * @param[in,out] aIterator A pointer to the Network Data iterator context. To get the first on-mesh entry 100 it should be set to OT_NETWORK_DATA_ITERATOR_INIT. 101 * @param[out] aConfig A pointer to the On Mesh Prefix information. 102 * 103 * @retval OT_ERROR_NONE Successfully found the next On Mesh prefix. 104 * @retval OT_ERROR_NOT_FOUND No subsequent On Mesh prefix exists in the Thread Network Data. 105 */ 106 otError otBorderRouterGetNextOnMeshPrefix(otInstance *aInstance, 107 otNetworkDataIterator *aIterator, 108 otBorderRouterConfig *aConfig); 109 110 /** 111 * Add an external route configuration to the local network data. 112 * 113 * @param[in] aInstance A pointer to an OpenThread instance. 114 * @param[in] aConfig A pointer to the external route configuration. 115 * 116 * @retval OT_ERROR_NONE Successfully added the configuration to the local network data. 117 * @retval OT_ERROR_INVALID_ARGS One or more configuration parameters were invalid. 118 * @retval OT_ERROR_NO_BUFS Not enough room is available to add the configuration to the local network data. 119 * 120 * @sa otBorderRouterRemoveRoute 121 * @sa otBorderRouterRegister 122 */ 123 otError otBorderRouterAddRoute(otInstance *aInstance, const otExternalRouteConfig *aConfig); 124 125 /** 126 * Remove an external route configuration from the local network data. 127 * 128 * @param[in] aInstance A pointer to an OpenThread instance. 129 * @param[in] aPrefix A pointer to an IPv6 prefix. 130 * 131 * @retval OT_ERROR_NONE Successfully removed the configuration from the local network data. 132 * @retval OT_ERROR_NOT_FOUND Could not find the Border Router entry. 133 * 134 * @sa otBorderRouterAddRoute 135 * @sa otBorderRouterRegister 136 */ 137 otError otBorderRouterRemoveRoute(otInstance *aInstance, const otIp6Prefix *aPrefix); 138 139 /** 140 * Gets the next external route in the local Network Data. 141 * 142 * @param[in] aInstance A pointer to an OpenThread instance. 143 * @param[in,out] aIterator A pointer to the Network Data iterator context. To get the first external route entry 144 it should be set to OT_NETWORK_DATA_ITERATOR_INIT. 145 * @param[out] aConfig A pointer to the External Route information. 146 * 147 * @retval OT_ERROR_NONE Successfully found the next External Route. 148 * @retval OT_ERROR_NOT_FOUND No subsequent external route entry exists in the Thread Network Data. 149 */ 150 otError otBorderRouterGetNextRoute(otInstance *aInstance, 151 otNetworkDataIterator *aIterator, 152 otExternalRouteConfig *aConfig); 153 154 /** 155 * Immediately register the local network data with the Leader. 156 * 157 * @param[in] aInstance A pointer to an OpenThread instance. 158 * 159 * @retval OT_ERROR_NONE Successfully queued a Server Data Request message for delivery. 160 * 161 * @sa otBorderRouterAddOnMeshPrefix 162 * @sa otBorderRouterRemoveOnMeshPrefix 163 * @sa otBorderRouterAddRoute 164 * @sa otBorderRouterRemoveRoute 165 */ 166 otError otBorderRouterRegister(otInstance *aInstance); 167 168 /** 169 * Function pointer callback which is invoked when Network Data (local or leader) gets full. 170 * 171 * @param[in] aContext A pointer to arbitrary context information. 172 */ 173 typedef void (*otBorderRouterNetDataFullCallback)(void *aContext); 174 175 /** 176 * Sets the callback to indicate when Network Data gets full. 177 * 178 * Requires `OPENTHREAD_CONFIG_BORDER_ROUTER_SIGNAL_NETWORK_DATA_FULL`. 179 * 180 * The callback is invoked whenever: 181 * - The device is acting as a leader and receives a Network Data registration from a Border Router (BR) that it cannot 182 * add to Network Data (running out of space). 183 * - The device is acting as a BR and new entries cannot be added to its local Network Data. 184 * - The device is acting as a BR and tries to register its local Network Data entries with the leader, but determines 185 * that its local entries will not fit. 186 * 187 * @param[in] aInstance A pointer to an OpenThread instance. 188 * @param[in] aCallback The callback. 189 * @param[in] aContext A pointer to arbitrary context information used with @p aCallback. 190 */ 191 void otBorderRouterSetNetDataFullCallback(otInstance *aInstance, 192 otBorderRouterNetDataFullCallback aCallback, 193 void *aContext); 194 195 /** 196 * @} 197 */ 198 199 #ifdef __cplusplus 200 } // extern "C" 201 #endif 202 203 #endif // OPENTHREAD_BORDER_ROUTER_H_ 204
