thread_border_router_api.h

00001 /*
00002  * Copyright (c) 2014-2018, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: BSD-3-Clause
00004  *
00005  * Redistribution and use in source and binary forms, with or without
00006  * modification, are permitted provided that the following conditions are met:
00007  *
00008  * 1. Redistributions of source code must retain the above copyright
00009  *    notice, this list of conditions and the following disclaimer.
00010  * 2. Redistributions in binary form must reproduce the above copyright
00011  *    notice, this list of conditions and the following disclaimer in the
00012  *    documentation and/or other materials provided with the distribution.
00013  * 3. Neither the name of the copyright holder nor the
00014  *    names of its contributors may be used to endorse or promote products
00015  *    derived from this software without specific prior written permission.
00016  *
00017  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00018  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00019  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00020  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
00021  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00022  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00023  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00024  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00025  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00026  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00027  * POSSIBILITY OF SUCH DAMAGE.
00028  */
00029 
00030 /**
00031  * \file thread_border_router_api.h
00032  * \brief Thread border router application interface.
00033  *
00034  * This file contains functions for managing Thread border router features.
00035  * Border routers can set up services in the Thread network including routes,
00036  * DHCPv6 servers, on-mesh prefixes and services.
00037  *
00038  */
00039 
00040 #ifndef THREAD_BORDER_ROUTER_API_H_
00041 #define THREAD_BORDER_ROUTER_API_H_
00042 
00043 #include "ns_types.h"
00044 
00045 /**
00046  * \brief Border router network data structure.
00047  */
00048 typedef struct thread_border_router_info_t {
00049     unsigned            Prf: 2;               /**< Prefix preference, 01 = High, 00 = Default, 11 = Low, 10 = Reserved. */
00050     bool                P_preferred: 1;       /**< Address is considered preferred address. */
00051     bool                P_slaac: 1;           /**< Allowed to configure a new address */
00052     bool                P_dhcp: 1;            /**< DHCPv6 server is available in the network. */
00053     bool                P_configure: 1;       /**< DHCPv6 agent provides other configuration. */
00054     bool                P_default_route: 1;   /**< This device provides the default route. */
00055     bool                P_on_mesh: 1;         /**< This prefix is considered to be on-mesh */
00056     bool                P_nd_dns: 1;          /**< this border router is able to provide DNS information */
00057     bool                P_res1: 1;            /**< First reserved bit */
00058     bool                stableData: 1;        /**< This data is stable and expected to be available at least 48h. */
00059 } thread_border_router_info_t;
00060 
00061 /**
00062  * \brief Create local service that is provided to the Thread network.
00063  * If a prefix exists it is updated. For example, when removing SLAAC (Stateless Address Autoconfiguration) you should modify the prefix
00064  * first to remove the creation of new addresses and after a while, remove the prefix.
00065  *
00066  * When you have configured the services locally, you need to call
00067  * thread_border_router_publish to make the services available in the network.
00068  *
00069  * \param interface_id Network interface ID.
00070  * \param prefix_ptr Pointer prefix.
00071  * \param prefix_len Length of prefix.
00072  * \param prefix_info_ptr Prefix service structure configuring the published service.
00073  *
00074  * \return 0, Set OK.
00075  * \return <0 Set not OK.
00076  */
00077 int thread_border_router_prefix_add(int8_t interface_id, uint8_t *prefix_ptr, uint8_t prefix_len, thread_border_router_info_t *prefix_info_ptr);
00078 
00079 /**
00080  * \brief Delete local service.
00081  *
00082  * \param interface_id Network interface ID.
00083  * \param prefix_ptr Pointer prefix.
00084  * \param prefix_len Length of prefix.
00085  *
00086  * \return 0, Set OK.
00087  * \return <0 Set not OK.
00088  */
00089 int thread_border_router_prefix_delete(int8_t interface_id, uint8_t *prefix_ptr, uint8_t prefix_len);
00090 
00091 /**
00092  * \brief Add a new route to the Thread network. Other devices can use the route.
00093  * For example, 0::0/0 means that this device provides the default route.
00094  * For example, 2001::0/64 means that this device provides a more specific route.
00095  *
00096  * If a prefix exists it is updated.
00097  *
00098  * \param interface_id Network interface ID.
00099  * \param prefix_ptr Pointer prefix. Can be NULL for the default route.
00100  * \param prefix_len Length of prefix.
00101  * \param stable This data is stable and expected to be available at least 48h.
00102  * \param prf Route preference, 01 = High, 00 = Default, 11 = Low, 10 = Reserved.
00103  *
00104  * \return 0, Set OK.
00105  * \return <0 Set not OK.
00106  */
00107 int thread_border_router_route_add(int8_t interface_id, uint8_t *prefix_ptr, uint8_t prefix_len, bool stable, int8_t prf);
00108 
00109 /**
00110  * \brief Delete locally served route.
00111  *
00112  * \param interface_id Network interface ID.
00113  * \param prefix_ptr Pointer prefix.
00114  * \param prefix_len Length of prefix.
00115  *
00116  * \return 0, Set OK.
00117  * \return <0 Set not OK.
00118  */
00119 int thread_border_router_route_delete(int8_t interface_id, uint8_t *prefix_ptr, uint8_t prefix_len);
00120 
00121 /**
00122  * \brief Add or modify a local service.
00123  *
00124  * \param interface_id Network interface ID.
00125  * \param service_data Pointer to a byte string specifying the type of service.
00126  * \param service_len Length of service data.
00127  * \param sid Service Type ID, a value between 0 and 15, inclusive, assigned to this service data.
00128  * \param enterprise_number Enterprise number of the vendor that defined the type of the server.
00129  * \param server_data Pointer to a byte string containing server-specific information.
00130  * \param server_data_len Length of server data.
00131  * \param stable This data is stable and expected to be available at least 48h.
00132  *
00133  * \return 0, Addition OK.
00134  * \return <0 Addition not OK.
00135  */
00136 int thread_border_router_service_add(int8_t interface_id, uint8_t *service_data, uint8_t service_len, uint8_t sid, uint32_t enterprise_number, uint8_t *server_data, uint8_t server_data_len, bool stable);
00137 
00138 /**
00139  * \brief Delete local service by service data and enterprise number.
00140  *
00141  * \param interface_id Network interface ID.
00142  * \param service_data Pointer to a byte string specifying the type of service.
00143  * \param service_len Length of service.
00144  * \param enterprise_number Enterprise number of the vendor that defined the type of the server.
00145  *
00146  * \return 0, Delete OK.
00147  * \return <0 Delete not OK.
00148  */
00149 int thread_border_router_service_delete(int8_t interface_id, uint8_t *service_data, uint8_t service_len, uint32_t enterprise_number);
00150 
00151 /**
00152  * \brief Publish local services to Thread network.
00153  *
00154  * If local services are deleted before calling this, all services are deregistered from the network.
00155  *
00156  * \param interface_id Network interface ID.
00157  *
00158  * \return 0, Push OK.
00159  * \return <0 Push not OK.
00160  */
00161 int thread_border_router_publish(int8_t interface_id);
00162 
00163 /**
00164  * \brief Clear the local service list.
00165  *
00166  * \param interface_id Network interface ID.
00167  *
00168  * \return 0, Push OK.
00169  * \return <0 Push not OK.
00170  */
00171 int thread_border_router_delete_all(int8_t interface_id);
00172 
00173 /**
00174  * \brief Set Recursive DNS server (RDNSS) option that is encoded according to RFC6106.
00175  * Setting a new RDNSS will overwrite previous RDNSS option. Set RNDDS will be used
00176  * until it is cleared.
00177  *
00178  * \param interface_id Network interface ID.
00179  * \param recursive_dns_server_option Recursive DNS server option encoded according to rfc6106, can be NULL to clear existing RDNSS.
00180  * \param recursive_dns_server_option_len Length of the recursive_dns_server_option in bytes.
00181  *
00182  * \return 0, Option saved OK.
00183  * \return <0 when error occurs during option processing.
00184  */
00185 int thread_border_router_recursive_dns_server_option_set(int8_t interface_id, uint8_t *recursive_dns_server_option, uint16_t recursive_dns_server_option_len);
00186 
00187 /**
00188  * \brief Set DNS server search list (DNSSL) option that is encoded according to RFC6106.
00189  * Setting a new DNSSL will overwrite previous DNSSL option. Set DNSSL will be used
00190  * until it is cleared.
00191  *
00192  * \param interface_id Network interface ID.
00193  * \param dns_search_list_option DNS search list option encoded according to rfc6106, can be NULL to clear existing DNSSL.
00194  * \param search_list_option_len Length of the dns_search_list_option in bytes.
00195  *
00196  * \return 0, Option saved OK.
00197  * \return <0 when error occurs during option processing.
00198  */
00199 int thread_border_router_dns_search_list_option_set(int8_t interface_id, uint8_t *dns_search_list_option, uint16_t search_list_option_len);
00200 
00201 /**
00202  * \brief Callback type for Thread network data TLV registration
00203  *
00204  * \param interface_id Network interface ID.
00205  * \param network_data_tlv Thread Network data TLV as specified in Thread specification.
00206  * \param network_data_tlv_length length of the network data TLV.
00207  */
00208 typedef void (thread_network_data_tlv_cb)(int8_t interface_id, uint8_t *network_data_tlv, uint16_t network_data_tlv_length);
00209 
00210 /**
00211  * \brief Register callback function to receive thread network data TLV in byte array. For the first time the callback
00212  * will be called before returning from the function. Afterwards the callback will be called when there is a change
00213  * to the network data or when the network data is advertised. Application is not allowed to block the callback execution
00214  * and must make a copy of the network data if it is needed afterwards.
00215  *
00216  * Setting nwk_data_cb to NULL will prevent further calls to the callback function.
00217  *
00218  * \param interface_id Network interface ID.
00219  * \param nwk_data_cb callback function to receive network data TLV in byte array as specified in the Thread specification.
00220  *
00221  * \return 0, Callback function registered successfully.
00222  * \return <0 when error occurs during registering the callback function.
00223  */
00224 int thread_border_router_network_data_callback_register(int8_t interface_id, thread_network_data_tlv_cb *nwk_data_cb);
00225 
00226 /**
00227  * Find Prefix TLV from the Network Data TLV byte array.
00228  *
00229  * \param network_data_tlv [IN] Network data TLV in byte array.
00230  * \param network_data_tlv_length [IN] Length of the network data TLV byte array in bytes.
00231  * \param prefix_tlv [IN] pointer to the previous prefix_tlv, NULL if previous TLV not known.
00232  *                   [OUT] Pointer to the prefix TLV found.
00233  * \param stable [OUT] value set to true if found TLV is stable, false otherwise.
00234  *
00235  * \return Length of the found Prefix TLV
00236  * \return 0 if TLV is empty or no Prefix TLV found.
00237  * \return negative value indicates error in input parameters.
00238  */
00239 int thread_border_router_prefix_tlv_find(uint8_t *network_data_tlv, uint16_t network_data_tlv_length, uint8_t **prefix_tlv, bool *stable);
00240 
00241 /**
00242  * Find Border router TLV from the Network Data TLV (under Prefix TLV) byte array.
00243  *
00244  * \param prefix_tlv [IN] Network data TLV in byte array.
00245  * \param prefix_tlv_length [IN] Length of the Network data TLV byte array in bytes.
00246  * \param border_router_tlv [IN] pointer to the previous Border Router TLV, NULL if not known.
00247  *                          [OUT] Pointer to the Border Router TLV found.
00248  * \param stable [OUT] value set to true if found TLV is stable, false otherwise
00249  *
00250  * \return Length of the Prefix found
00251  * \return 0 if TLV is empty or no TLV found.
00252  * \return negative value indicates error in input parameters.
00253  */
00254 int thread_border_router_tlv_find(uint8_t *prefix_tlv, uint16_t prefix_tlv_length, uint8_t **border_router_tlv, bool *stable);
00255 
00256 /**
00257  * Find Service TLV from the Network Data TLV byte array.
00258  *
00259  * \param network_data_tlv [IN] Network data TLV in byte array.
00260  * \param network_data_tlv_length [IN] Length of the network data TLV byte array in bytes.
00261  * \param service_tlv [IN] pointer to the previous Service TLV, NULL if previous TLV not known.
00262  *                   [OUT] Pointer to the Service TLV found.
00263  * \param stable [OUT] value set to true if found TLV is stable, false otherwise.
00264  *
00265  * \return Length of the found Service TLV
00266  * \return 0 if TLV is empty or no Service TLV found.
00267  * \return negative value indicates error in input parameters.
00268  */
00269 int thread_border_router_service_tlv_find(uint8_t *network_data_tlv, uint16_t network_data_tlv_length, uint8_t **service_tlv, bool *stable);
00270 
00271 /**
00272  * Find Server TLV from the Network Data TLV (under Service TLV) byte array.
00273  *
00274  * \param service_tlv [IN] Network data TLV in byte array.
00275  * \param service_tlv_length [IN] Length of the Network data TLV byte array in bytes.
00276  * \param server_tlv [IN] pointer to the previous Server TLV, NULL if not known.
00277  *                          [OUT] Pointer to the Server TLV found.
00278  * \param stable [OUT] value set to true if found TLV is stable, false otherwise
00279  *
00280  * \return Length of the Prefix found
00281  * \return 0 if TLV is empty or no TLV found.
00282  * \return negative value indicates error in input parameters.
00283  */
00284 int thread_border_router_server_tlv_find(uint8_t *service_tlv, uint16_t service_tlv_length, uint8_t **server_tlv, bool *stable);
00285 
00286 /**
00287  * Determine context ID from the Network Data TLV (under Prefix TLV) byte array.
00288  *
00289  * \param prefix_tlv [IN] Prefix TLV in byte array.
00290  * \param prefix_tlv_length [IN] Length of the Prefix TLV byte array in bytes.
00291  *
00292  * \return The context ID value found
00293  * \return -1 if error in input parameters.
00294  * \return -2 if no context ID value found.
00295  */
00296 int thread_border_router_prefix_context_id(uint8_t *prefix_tlv, uint16_t prefix_tlv_length);
00297 
00298 /**
00299  * Start mDNS responder service. The responder will respond to DNS-SD queries and send announcement when
00300  * Thread network data is updated.
00301  *
00302  * The mDNS responder can be closed by calling thread_border_router_mdns_responder_stop(). Closing the Thread
00303  * network interface will stop the mDNS responder automatically.
00304  *
00305  * \param interface_id interface ID of the Thread network
00306  * \param interface_id_mdns interface where mDNS messaging occurs
00307  * \param service_name mDNS instance name
00308  *
00309  * \return 0 on success
00310  * \return <0 in case of errors
00311  *
00312  */
00313 int thread_border_router_mdns_responder_start(int8_t interface_id, int8_t interface_id_mdns, const char *service_name);
00314 
00315 /**
00316  * Stop mDNS responder service
00317  *
00318  * \return 0 on success
00319  * \return <0 in case of errors
00320  *
00321  */
00322 int thread_border_router_mdns_responder_stop(void);
00323 #endif /* THREAD_BORDER_ROUTER_API_H_ */