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