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/ip6.h> 39 #include <openthread/netdata.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @addtogroup api-border-router 47 * 48 * @brief 49 * This module includes functions to manage local network data with the OpenThread Border Router. 50 * 51 * @{ 52 * 53 */ 54 55 /** 56 * This method initializes the Border Routing Manager on given infrastructure interface. 57 * 58 * @note This method MUST be called before any other otBorderRouting* APIs. 59 * 60 * @param[in] aInstance A pointer to an OpenThread instance. 61 * @param[in] aInfraIfIndex The infrastructure interface index. 62 * @param[in] aInfraIfIsRunning A boolean that indicates whether the infrastructure 63 * interface is running. 64 * 65 * @retval OT_ERROR_NONE Successfully started the Border Routing Manager on given infrastructure. 66 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager has already been initialized. 67 * @retval OT_ERROR_INVALID_ARGS The index of the infrastructure interface is not valid. 68 * @retval OT_ERROR_FAILED Internal failure. Usually due to failure in generating random prefixes. 69 * 70 * @sa otPlatInfraIfStateChanged. 71 * 72 */ 73 otError otBorderRoutingInit(otInstance *aInstance, uint32_t aInfraIfIndex, bool aInfraIfIsRunning); 74 75 /** 76 * This method enables/disables the Border Routing Manager. 77 * 78 * @note The Border Routing Manager is disabled by default. 79 * 80 * @param[in] aInstance A pointer to an OpenThread instance. 81 * @param[in] aEnabled A boolean to enable/disable the routing manager. 82 * 83 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 84 * @retval OT_ERROR_NONE Successfully enabled/disabled the Border Routing Manager. 85 * 86 */ 87 otError otBorderRoutingSetEnabled(otInstance *aInstance, bool aEnabled); 88 89 /** 90 * This method returns the off-mesh-routable (OMR) prefix. 91 * 92 * The randomly generated 64-bit prefix will be published 93 * in the Thread network if there isn't already an OMR prefix. 94 * 95 * @param[in] aInstance A pointer to an OpenThread instance. 96 * @param[out] aPrefix A pointer to where the prefix will be output to. 97 * 98 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 99 * @retval OT_ERROR_NONE Successfully retrieved the OMR prefix. 100 * 101 */ 102 otError otBorderRoutingGetOmrPrefix(otInstance *aInstance, otIp6Prefix *aPrefix); 103 104 /** 105 * This method returns the on-link prefix for the adjacent infrastructure link. 106 * 107 * The randomly generated 64-bit prefix will be advertised 108 * on the infrastructure link if there isn't already a usable 109 * on-link prefix being advertised on the link. 110 * 111 * @param[in] aInstance A pointer to an OpenThread instance. 112 * @param[out] aPrefix A pointer to where the prefix will be output to. 113 * 114 * @retval OT_ERROR_INVALID_STATE The Border Routing Manager is not initialized yet. 115 * @retval OT_ERROR_NONE Successfully retrieved the on-link prefix. 116 * 117 */ 118 otError otBorderRoutingGetOnLinkPrefix(otInstance *aInstance, otIp6Prefix *aPrefix); 119 120 /** 121 * This method provides a full or stable copy of the local Thread Network Data. 122 * 123 * @param[in] aInstance A pointer to an OpenThread instance. 124 * @param[in] aStable TRUE when copying the stable version, FALSE when copying the full version. 125 * @param[out] aData A pointer to the data buffer. 126 * @param[inout] aDataLength On entry, size of the data buffer pointed to by @p aData. 127 * On exit, number of copied bytes. 128 */ 129 otError otBorderRouterGetNetData(otInstance *aInstance, bool aStable, uint8_t *aData, uint8_t *aDataLength); 130 131 /** 132 * Add a border router configuration to the local network data. 133 * 134 * @param[in] aInstance A pointer to an OpenThread instance. 135 * @param[in] aConfig A pointer to the border router configuration. 136 * 137 * @retval OT_ERROR_NONE Successfully added the configuration to the local network data. 138 * @retval OT_ERROR_INVALID_ARGS One or more configuration parameters were invalid. 139 * @retval OT_ERROR_NO_BUFS Not enough room is available to add the configuration to the local network data. 140 * 141 * @sa otBorderRouterRemoveOnMeshPrefix 142 * @sa otBorderRouterRegister 143 */ 144 otError otBorderRouterAddOnMeshPrefix(otInstance *aInstance, const otBorderRouterConfig *aConfig); 145 146 /** 147 * Remove a border router configuration from the local network data. 148 * 149 * @param[in] aInstance A pointer to an OpenThread instance. 150 * @param[in] aPrefix A pointer to an IPv6 prefix. 151 * 152 * @retval OT_ERROR_NONE Successfully removed the configuration from the local network data. 153 * @retval OT_ERROR_NOT_FOUND Could not find the Border Router entry. 154 * 155 * @sa otBorderRouterAddOnMeshPrefix 156 * @sa otBorderRouterRegister 157 */ 158 otError otBorderRouterRemoveOnMeshPrefix(otInstance *aInstance, const otIp6Prefix *aPrefix); 159 160 /** 161 * This function gets the next On Mesh Prefix in the local Network Data. 162 * 163 * @param[in] aInstance A pointer to an OpenThread instance. 164 * @param[inout] aIterator A pointer to the Network Data iterator context. To get the first on-mesh entry 165 it should be set to OT_NETWORK_DATA_ITERATOR_INIT. 166 * @param[out] aConfig A pointer to the On Mesh Prefix information. 167 * 168 * @retval OT_ERROR_NONE Successfully found the next On Mesh prefix. 169 * @retval OT_ERROR_NOT_FOUND No subsequent On Mesh prefix exists in the Thread Network Data. 170 * 171 */ 172 otError otBorderRouterGetNextOnMeshPrefix(otInstance * aInstance, 173 otNetworkDataIterator *aIterator, 174 otBorderRouterConfig * aConfig); 175 176 /** 177 * Add an external route configuration to the local network data. 178 * 179 * @param[in] aInstance A pointer to an OpenThread instance. 180 * @param[in] aConfig A pointer to the external route configuration. 181 * 182 * @retval OT_ERROR_NONE Successfully added the configuration to the local network data. 183 * @retval OT_ERROR_INVALID_ARGS One or more configuration parameters were invalid. 184 * @retval OT_ERROR_NO_BUFS Not enough room is available to add the configuration to the local network data. 185 * 186 * @sa otBorderRouterRemoveRoute 187 * @sa otBorderRouterRegister 188 */ 189 otError otBorderRouterAddRoute(otInstance *aInstance, const otExternalRouteConfig *aConfig); 190 191 /** 192 * Remove an external route configuration from the local network data. 193 * 194 * @param[in] aInstance A pointer to an OpenThread instance. 195 * @param[in] aPrefix A pointer to an IPv6 prefix. 196 * 197 * @retval OT_ERROR_NONE Successfully removed the configuration from the local network data. 198 * @retval OT_ERROR_NOT_FOUND Could not find the Border Router entry. 199 * 200 * @sa otBorderRouterAddRoute 201 * @sa otBorderRouterRegister 202 */ 203 otError otBorderRouterRemoveRoute(otInstance *aInstance, const otIp6Prefix *aPrefix); 204 205 /** 206 * This function gets the next external route in the local Network Data. 207 * 208 * @param[in] aInstance A pointer to an OpenThread instance. 209 * @param[inout] aIterator A pointer to the Network Data iterator context. To get the first external route entry 210 it should be set to OT_NETWORK_DATA_ITERATOR_INIT. 211 * @param[out] aConfig A pointer to the External Route information. 212 * 213 * @retval OT_ERROR_NONE Successfully found the next External Route. 214 * @retval OT_ERROR_NOT_FOUND No subsequent external route entry exists in the Thread Network Data. 215 * 216 */ 217 otError otBorderRouterGetNextRoute(otInstance * aInstance, 218 otNetworkDataIterator *aIterator, 219 otExternalRouteConfig *aConfig); 220 221 /** 222 * Immediately register the local network data with the Leader. 223 * 224 * @param[in] aInstance A pointer to an OpenThread instance. 225 * 226 * @retval OT_ERROR_NONE Successfully queued a Server Data Request message for delivery. 227 * 228 * @sa otBorderRouterAddOnMeshPrefix 229 * @sa otBorderRouterRemoveOnMeshPrefix 230 * @sa otBorderRouterAddRoute 231 * @sa otBorderRouterRemoveRoute 232 */ 233 otError otBorderRouterRegister(otInstance *aInstance); 234 235 /** 236 * @} 237 * 238 */ 239 240 #ifdef __cplusplus 241 } // extern "C" 242 #endif 243 244 #endif // OPENTHREAD_BORDER_ROUTER_H_ 245
