thread_border_router_api.h

00001 /*
00002  * Copyright (c) 2014-2017, 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                stableData: 1;        /**< This data is stable and expected to be available at least 48h. */
00058 } thread_border_router_info_t;
00059 
00060 /**
00061  * \brief Create local service that is provided to the Thread network.
00062  * If a prefix exists it is updated. For example, when removing SLAAC (Stateless Address Autoconfiguration) you should modify the prefix
00063  * first to remove the creation of new addresses and after a while, remove the prefix.
00064  *
00065  * When you have configured the services locally, you need to call
00066  * thread_border_router_publish to make the services available in the network.
00067  *
00068  * \param interface_id Network interface ID.
00069  * \param prefix_ptr Pointer prefix.
00070  * \param prefix_len Length of prefix.
00071  * \param prefix_info_ptr Prefix service structure configuring the published service.
00072  *
00073  * \return 0, Set OK.
00074  * \return <0 Set not OK.
00075  */
00076 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);
00077 
00078 /**
00079  * \brief Delete local service.
00080  *
00081  * \param interface_id Network interface ID.
00082  * \param prefix_ptr Pointer prefix.
00083  * \param prefix_len Length of prefix.
00084  *
00085  * \return 0, Set OK.
00086  * \return <0 Set not OK.
00087  */
00088 int thread_border_router_prefix_delete(int8_t interface_id, uint8_t *prefix_ptr, uint8_t prefix_len);
00089 
00090 /**
00091  * \brief Add a new route to the Thread network. Other devices can use the route.
00092  * For example, 0::0/0 means that this device provides the default route.
00093  * For example, 2001::0/64 means that this device provides a more specific route.
00094  *
00095  * If a prefix exists it is updated.
00096  *
00097  * \param interface_id Network interface ID.
00098  * \param prefix_ptr Pointer prefix. Can be NULL for the default route.
00099  * \param prefix_len Length of prefix.
00100  * \param stable This data is stable and expected to be available at least 48h.
00101  * \param prf Route preference, 01 = High, 00 = Default, 11 = Low, 10 = Reserved.
00102  *
00103  * \return 0, Set OK.
00104  * \return <0 Set not OK.
00105  */
00106 int thread_border_router_route_add(int8_t interface_id, uint8_t *prefix_ptr, uint8_t prefix_len, bool stable, int8_t prf);
00107 
00108 /**
00109  * \brief Delete locally served route.
00110  *
00111  * \param interface_id Network interface ID.
00112  * \param prefix_ptr Pointer prefix.
00113  * \param prefix_len Length of prefix.
00114  *
00115  * \return 0, Set OK.
00116  * \return <0 Set not OK.
00117  */
00118 int thread_border_router_route_delete(int8_t interface_id, uint8_t *prefix_ptr, uint8_t prefix_len);
00119 
00120 /**
00121  * \brief Add or modify a local service.
00122  *
00123  * \param interface_id Network interface ID.
00124  * \param service_data Pointer to a byte string specifying the type of service.
00125  * \param service_len Length of service data.
00126  * \param sid Service Type ID, a value between 0 and 15, inclusive, assigned to this service data.
00127  * \param enterprise_number Enterprise number of the vendor that defined the type of the server.
00128  * \param server_data Pointer to a byte string containing server-specific information.
00129  * \param server_data_len Length of server data.
00130  * \param stable This data is stable and expected to be available at least 48h.
00131  *
00132  * \return 0, Addition OK.
00133  * \return <0 Addition not OK.
00134  */
00135 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);
00136 
00137 /**
00138  * \brief Delete local service by service data and enterprise number.
00139  *
00140  * \param interface_id Network interface ID.
00141  * \param service_data Pointer to a byte string specifying the type of service.
00142  * \param service_len Length of service.
00143  * \param enterprise_number Enterprise number of the vendor that defined the type of the server.
00144  *
00145  * \return 0, Delete OK.
00146  * \return <0 Delete not OK.
00147  */
00148 int thread_border_router_service_delete(int8_t interface_id, uint8_t *service_data, uint8_t service_len, uint32_t enterprise_number);
00149 
00150 /**
00151  * \brief Publish local services to Thread network.
00152  *
00153  * If local services are deleted before calling this, all services are deregistered from the network.
00154  *
00155  * \param interface_id Network interface ID.
00156  *
00157  * \return 0, Push OK.
00158  * \return <0 Push not OK.
00159  */
00160 int thread_border_router_publish(int8_t interface_id);
00161 
00162 /**
00163  * \brief Clear the local service list.
00164  *
00165  * \param interface_id Network interface ID.
00166  *
00167  * \return 0, Push OK.
00168  * \return <0 Push not OK.
00169  */
00170 int thread_border_router_delete_all(int8_t interface_id);
00171 
00172 /**
00173  * \brief Set Recursive DNS server (RDNSS) option that is encoded according to RFC6106.
00174  * Setting a new RDNSS will overwrite previous RDNSS option. Set RNDDS will be used
00175  * until it is cleared.
00176  *
00177  * \param interface_id Network interface ID.
00178  * \param recursive_dns_server_option Recursive DNS server option encoded according to rfc6106, can be NULL to clear existing RDNSS.
00179  * \param recursive_dns_server_option_len Length of the recursive_dns_server_option in bytes.
00180  *
00181  * \return 0, Option saved OK.
00182  * \return <0 when error occurs during option processing.
00183  */
00184 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);
00185 
00186 /**
00187  * \brief Set DNS server search list (DNSSL) option that is encoded according to RFC6106.
00188  * Setting a new DNSSL will overwrite previous DNSSL option. Set DNSSL will be used
00189  * until it is cleared.
00190  *
00191  * \param interface_id Network interface ID.
00192  * \param dns_search_list_option DNS search list option encoded according to rfc6106, can be NULL to clear existing DNSSL.
00193  * \param search_list_option_len Length of the dns_search_list_option in bytes.
00194  *
00195  * \return 0, Option saved OK.
00196  * \return <0 when error occurs during option processing.
00197  */
00198 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);
00199 
00200 /**
00201  * \brief Callback type for Thread network data TLV registration
00202  *
00203  * \param interface_id Network interface ID.
00204  * \param network_data_tlv Thread Network data TLV as specified in Thread specification.
00205  * \param network_data_tlv_length length of the network data TLV.
00206  */
00207 typedef void (thread_network_data_tlv_cb)(int8_t interface_id, uint8_t *network_data_tlv, uint16_t network_data_tlv_length);
00208 
00209 /**
00210  * \brief Register callback function to receive thread network data TLV in byte array. For the first time the callback
00211  * will be called before returning from the function. Afterwards the callback will be called when there is a change
00212  * to the network data or when the network data is advertised. Application is not allowed to block the callback execution
00213  * and must make a copy of the network data if it is needed afterwards.
00214  *
00215  * Setting nwk_data_cb to NULL will prevent further calls to the callback function.
00216  *
00217  * \param interface_id Network interface ID.
00218  * \param nwk_data_cb callback function to receive network data TLV in byte array as specified in the Thread specification.
00219  *
00220  * \return 0, Callback function registered successfully.
00221  * \return <0 when error occurs during registering the callback function.
00222  */
00223 int thread_border_router_network_data_callback_register(int8_t interface_id, thread_network_data_tlv_cb* nwk_data_cb);
00224 
00225 /**
00226  * Find Prefix TLV from the Network Data TLV byte array.
00227  *
00228  * \param network_data_tlv [IN] Network data TLV in byte array.
00229  * \param network_data_tlv_length [IN] Length of the network data TLV byte array in bytes.
00230  * \param prefix_tlv [IN] pointer to the previous prefix_tlv, NULL if previous TLV not known.
00231  *                   [OUT] Pointer to the prefix TLV found.
00232  * \param stable [OUT] value set to true if found TLV is stable, false otherwise.
00233  *
00234  * \return Length of the found Prefix TLV
00235  * \return 0 if TLV is empty or no Prefix TLV found.
00236  * \return negative value indicates error in input parameters.
00237  */
00238 int thread_border_router_prefix_tlv_find(uint8_t* network_data_tlv, uint16_t network_data_tlv_length, uint8_t** prefix_tlv, bool* stable);
00239 
00240 /**
00241  * Find Border router TLV from the Network Data TLV (under Prefix TLV) byte array.
00242  *
00243  * \param prefix_tlv [IN] Network data TLV in byte array.
00244  * \param prefix_tlv_length [IN] Length of the Network data TLV byte array in bytes.
00245  * \param border_router_tlv [IN] pointer to the previous Border Router TLV, NULL if not known.
00246  *                          [OUT] Pointer to the Border Router TLV found.
00247  * \param stable [OUT] value set to true if found TLV is stable, false otherwise
00248  *
00249  * \return Length of the Prefix found
00250  * \return 0 if TLV is empty or no TLV found.
00251  * \return negative value indicates error in input parameters.
00252  */
00253 int thread_border_router_tlv_find(uint8_t* prefix_tlv, uint16_t prefix_tlv_length, uint8_t** border_router_tlv, bool* stable);
00254 
00255 /**
00256  * Find Service TLV from the Network Data TLV byte array.
00257  *
00258  * \param network_data_tlv [IN] Network data TLV in byte array.
00259  * \param network_data_tlv_length [IN] Length of the network data TLV byte array in bytes.
00260  * \param service_tlv [IN] pointer to the previous Service TLV, NULL if previous TLV not known.
00261  *                   [OUT] Pointer to the Service TLV found.
00262  * \param stable [OUT] value set to true if found TLV is stable, false otherwise.
00263  *
00264  * \return Length of the found Service TLV
00265  * \return 0 if TLV is empty or no Service TLV found.
00266  * \return negative value indicates error in input parameters.
00267  */
00268 int thread_border_router_service_tlv_find(uint8_t* network_data_tlv, uint16_t network_data_tlv_length, uint8_t** service_tlv, bool* stable);
00269 
00270 /**
00271  * Find Server TLV from the Network Data TLV (under Service TLV) byte array.
00272  *
00273  * \param service_tlv [IN] Network data TLV in byte array.
00274  * \param service_tlv_length [IN] Length of the Network data TLV byte array in bytes.
00275  * \param server_tlv [IN] pointer to the previous Server TLV, NULL if not known.
00276  *                          [OUT] Pointer to the Server TLV found.
00277  * \param stable [OUT] value set to true if found TLV is stable, false otherwise
00278  *
00279  * \return Length of the Prefix found
00280  * \return 0 if TLV is empty or no TLV found.
00281  * \return negative value indicates error in input parameters.
00282  */
00283 int thread_border_router_server_tlv_find(uint8_t* service_tlv, uint16_t service_tlv_length, uint8_t** server_tlv, bool* stable);
00284 
00285 /**
00286  * Determine context ID from the Network Data TLV (under Prefix TLV) byte array.
00287  *
00288  * \param prefix_tlv [IN] Prefix TLV in byte array.
00289  * \param prefix_tlv_length [IN] Length of the Prefix TLV byte array in bytes.
00290  *
00291  * \return The context ID value found
00292  * \return -1 if error in input parameters.
00293  * \return -2 if no context ID value found.
00294  */
00295 int thread_border_router_prefix_context_id(uint8_t *prefix_tlv, uint16_t prefix_tlv_length);
00296 
00297 /**
00298  * Start mDNS responder service. The responder will respond to DNS-SD queries and send announcement when
00299  * Thread network data is updated.
00300  *
00301  * The mDNS responder can be closed by calling thread_border_router_mdns_responder_stop(). Closing the Thread
00302  * network interface will stop the mDNS responder automatically.
00303  *
00304  * \param interface_id interface ID of the Thread network
00305  * \param interface_id_mdns interface where mDNS messaging occurs
00306  * \param service_name mDNS instance name
00307  *
00308  * \return 0 on success
00309  * \return <0 in case of errors
00310  *
00311  */
00312 int thread_border_router_mdns_responder_start(int8_t interface_id, int8_t interface_id_mdns, const char *service_name);
00313 
00314 /**
00315  * Stop mDNS responder service
00316  *
00317  * \return 0 on success
00318  * \return <0 in case of errors
00319  *
00320  */
00321 int thread_border_router_mdns_responder_stop(void);
00322 #endif /* THREAD_BORDER_ROUTER_API_H_ */