mirror of https://github.com/ARMmbed/mbed-os.git
324 lines
14 KiB
C
324 lines
14 KiB
C
/*
|
|
* Copyright (c) 2014-2018, Pelion and affiliates.
|
|
* SPDX-License-Identifier: BSD-3-Clause
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions are met:
|
|
*
|
|
* 1. Redistributions of source code must retain the above copyright
|
|
* notice, this list of conditions and the following disclaimer.
|
|
* 2. Redistributions in binary form must reproduce the above copyright
|
|
* notice, this list of conditions and the following disclaimer in the
|
|
* documentation and/or other materials provided with the distribution.
|
|
* 3. Neither the name of the copyright holder nor the
|
|
* names of its contributors may be used to endorse or promote products
|
|
* derived from this software without specific prior written permission.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
|
|
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
* POSSIBILITY OF SUCH DAMAGE.
|
|
*/
|
|
|
|
/**
|
|
* \file thread_border_router_api.h
|
|
* \brief Thread border router application interface.
|
|
*
|
|
* This file contains functions for managing Thread border router features.
|
|
* Border routers can set up services in the Thread network including routes,
|
|
* DHCPv6 servers, on-mesh prefixes and services.
|
|
*
|
|
*/
|
|
|
|
#ifndef THREAD_BORDER_ROUTER_API_H_
|
|
#define THREAD_BORDER_ROUTER_API_H_
|
|
|
|
#include "ns_types.h"
|
|
|
|
/**
|
|
* \brief Border router network data structure.
|
|
*/
|
|
typedef struct thread_border_router_info_t {
|
|
unsigned Prf: 2; /**< Prefix preference, 01 = High, 00 = Default, 11 = Low, 10 = Reserved. */
|
|
bool P_preferred: 1; /**< Address is considered preferred address. */
|
|
bool P_slaac: 1; /**< Allowed to configure a new address */
|
|
bool P_dhcp: 1; /**< DHCPv6 server is available in the network. */
|
|
bool P_configure: 1; /**< DHCPv6 agent provides other configuration. */
|
|
bool P_default_route: 1; /**< This device provides the default route. */
|
|
bool P_on_mesh: 1; /**< This prefix is considered to be on-mesh */
|
|
bool P_nd_dns: 1; /**< this border router is able to provide DNS information */
|
|
bool P_res1: 1; /**< First reserved bit */
|
|
bool stableData: 1; /**< This data is stable and expected to be available at least 48h. */
|
|
} thread_border_router_info_t;
|
|
|
|
/**
|
|
* \brief Create local service that is provided to the Thread network.
|
|
* If a prefix exists it is updated. For example, when removing SLAAC (Stateless Address Autoconfiguration) you should modify the prefix
|
|
* first to remove the creation of new addresses and after a while, remove the prefix.
|
|
*
|
|
* When you have configured the services locally, you need to call
|
|
* thread_border_router_publish to make the services available in the network.
|
|
*
|
|
* \param interface_id Network interface ID.
|
|
* \param prefix_ptr Pointer prefix.
|
|
* \param prefix_len Length of prefix.
|
|
* \param prefix_info_ptr Prefix service structure configuring the published service.
|
|
*
|
|
* \return 0, Set OK.
|
|
* \return <0 Set not OK.
|
|
*/
|
|
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);
|
|
|
|
/**
|
|
* \brief Delete local service.
|
|
*
|
|
* \param interface_id Network interface ID.
|
|
* \param prefix_ptr Pointer prefix.
|
|
* \param prefix_len Length of prefix.
|
|
*
|
|
* \return 0, Set OK.
|
|
* \return <0 Set not OK.
|
|
*/
|
|
int thread_border_router_prefix_delete(int8_t interface_id, uint8_t *prefix_ptr, uint8_t prefix_len);
|
|
|
|
/**
|
|
* \brief Add a new route to the Thread network. Other devices can use the route.
|
|
* For example, 0::0/0 means that this device provides the default route.
|
|
* For example, 2001::0/64 means that this device provides a more specific route.
|
|
*
|
|
* If a prefix exists it is updated.
|
|
*
|
|
* \param interface_id Network interface ID.
|
|
* \param prefix_ptr Pointer prefix. Can be NULL for the default route.
|
|
* \param prefix_len Length of prefix.
|
|
* \param stable This data is stable and expected to be available at least 48h.
|
|
* \param prf Route preference, 01 = High, 00 = Default, 11 = Low, 10 = Reserved.
|
|
*
|
|
* \return 0, Set OK.
|
|
* \return <0 Set not OK.
|
|
*/
|
|
int thread_border_router_route_add(int8_t interface_id, uint8_t *prefix_ptr, uint8_t prefix_len, bool stable, int8_t prf);
|
|
|
|
/**
|
|
* \brief Delete locally served route.
|
|
*
|
|
* \param interface_id Network interface ID.
|
|
* \param prefix_ptr Pointer prefix.
|
|
* \param prefix_len Length of prefix.
|
|
*
|
|
* \return 0, Set OK.
|
|
* \return <0 Set not OK.
|
|
*/
|
|
int thread_border_router_route_delete(int8_t interface_id, uint8_t *prefix_ptr, uint8_t prefix_len);
|
|
|
|
/**
|
|
* \brief Add or modify a local service.
|
|
*
|
|
* \param interface_id Network interface ID.
|
|
* \param service_data Pointer to a byte string specifying the type of service.
|
|
* \param service_len Length of service data.
|
|
* \param sid Service Type ID, a value between 0 and 15, inclusive, assigned to this service data.
|
|
* \param enterprise_number Enterprise number of the vendor that defined the type of the server.
|
|
* \param server_data Pointer to a byte string containing server-specific information.
|
|
* \param server_data_len Length of server data.
|
|
* \param stable This data is stable and expected to be available at least 48h.
|
|
*
|
|
* \return 0, Addition OK.
|
|
* \return <0 Addition not OK.
|
|
*/
|
|
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);
|
|
|
|
/**
|
|
* \brief Delete local service by service data and enterprise number.
|
|
*
|
|
* \param interface_id Network interface ID.
|
|
* \param service_data Pointer to a byte string specifying the type of service.
|
|
* \param service_len Length of service.
|
|
* \param enterprise_number Enterprise number of the vendor that defined the type of the server.
|
|
*
|
|
* \return 0, Delete OK.
|
|
* \return <0 Delete not OK.
|
|
*/
|
|
int thread_border_router_service_delete(int8_t interface_id, uint8_t *service_data, uint8_t service_len, uint32_t enterprise_number);
|
|
|
|
/**
|
|
* \brief Publish local services to Thread network.
|
|
*
|
|
* If local services are deleted before calling this, all services are deregistered from the network.
|
|
*
|
|
* \param interface_id Network interface ID.
|
|
*
|
|
* \return 0, Push OK.
|
|
* \return <0 Push not OK.
|
|
*/
|
|
int thread_border_router_publish(int8_t interface_id);
|
|
|
|
/**
|
|
* \brief Clear the local service list.
|
|
*
|
|
* \param interface_id Network interface ID.
|
|
*
|
|
* \return 0, Push OK.
|
|
* \return <0 Push not OK.
|
|
*/
|
|
int thread_border_router_delete_all(int8_t interface_id);
|
|
|
|
/**
|
|
* \brief Set Recursive DNS server (RDNSS) option that is encoded according to RFC6106.
|
|
* Setting a new RDNSS will overwrite previous RDNSS option. Set RNDDS will be used
|
|
* until it is cleared.
|
|
*
|
|
* \param interface_id Network interface ID.
|
|
* \param recursive_dns_server_option Recursive DNS server option encoded according to rfc6106, can be NULL to clear existing RDNSS.
|
|
* \param recursive_dns_server_option_len Length of the recursive_dns_server_option in bytes.
|
|
*
|
|
* \return 0, Option saved OK.
|
|
* \return <0 when error occurs during option processing.
|
|
*/
|
|
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);
|
|
|
|
/**
|
|
* \brief Set DNS server search list (DNSSL) option that is encoded according to RFC6106.
|
|
* Setting a new DNSSL will overwrite previous DNSSL option. Set DNSSL will be used
|
|
* until it is cleared.
|
|
*
|
|
* \param interface_id Network interface ID.
|
|
* \param dns_search_list_option DNS search list option encoded according to rfc6106, can be NULL to clear existing DNSSL.
|
|
* \param search_list_option_len Length of the dns_search_list_option in bytes.
|
|
*
|
|
* \return 0, Option saved OK.
|
|
* \return <0 when error occurs during option processing.
|
|
*/
|
|
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);
|
|
|
|
/**
|
|
* \brief Callback type for Thread network data TLV registration
|
|
*
|
|
* \param interface_id Network interface ID.
|
|
* \param network_data_tlv Thread Network data TLV as specified in Thread specification.
|
|
* \param network_data_tlv_length length of the network data TLV.
|
|
*/
|
|
typedef void (thread_network_data_tlv_cb)(int8_t interface_id, uint8_t *network_data_tlv, uint16_t network_data_tlv_length);
|
|
|
|
/**
|
|
* \brief Register callback function to receive thread network data TLV in byte array. For the first time the callback
|
|
* will be called before returning from the function. Afterwards the callback will be called when there is a change
|
|
* to the network data or when the network data is advertised. Application is not allowed to block the callback execution
|
|
* and must make a copy of the network data if it is needed afterwards.
|
|
*
|
|
* Setting nwk_data_cb to NULL will prevent further calls to the callback function.
|
|
*
|
|
* \param interface_id Network interface ID.
|
|
* \param nwk_data_cb callback function to receive network data TLV in byte array as specified in the Thread specification.
|
|
*
|
|
* \return 0, Callback function registered successfully.
|
|
* \return <0 when error occurs during registering the callback function.
|
|
*/
|
|
int thread_border_router_network_data_callback_register(int8_t interface_id, thread_network_data_tlv_cb *nwk_data_cb);
|
|
|
|
/**
|
|
* Find Prefix TLV from the Network Data TLV byte array.
|
|
*
|
|
* \param network_data_tlv [IN] Network data TLV in byte array.
|
|
* \param network_data_tlv_length [IN] Length of the network data TLV byte array in bytes.
|
|
* \param prefix_tlv [IN] pointer to the previous prefix_tlv, NULL if previous TLV not known.
|
|
* [OUT] Pointer to the prefix TLV found.
|
|
* \param stable [OUT] value set to true if found TLV is stable, false otherwise.
|
|
*
|
|
* \return Length of the found Prefix TLV
|
|
* \return 0 if TLV is empty or no Prefix TLV found.
|
|
* \return negative value indicates error in input parameters.
|
|
*/
|
|
int thread_border_router_prefix_tlv_find(uint8_t *network_data_tlv, uint16_t network_data_tlv_length, uint8_t **prefix_tlv, bool *stable);
|
|
|
|
/**
|
|
* Find Border router TLV from the Network Data TLV (under Prefix TLV) byte array.
|
|
*
|
|
* \param prefix_tlv [IN] Network data TLV in byte array.
|
|
* \param prefix_tlv_length [IN] Length of the Network data TLV byte array in bytes.
|
|
* \param border_router_tlv [IN] pointer to the previous Border Router TLV, NULL if not known.
|
|
* [OUT] Pointer to the Border Router TLV found.
|
|
* \param stable [OUT] value set to true if found TLV is stable, false otherwise
|
|
*
|
|
* \return Length of the Prefix found
|
|
* \return 0 if TLV is empty or no TLV found.
|
|
* \return negative value indicates error in input parameters.
|
|
*/
|
|
int thread_border_router_tlv_find(uint8_t *prefix_tlv, uint16_t prefix_tlv_length, uint8_t **border_router_tlv, bool *stable);
|
|
|
|
/**
|
|
* Find Service TLV from the Network Data TLV byte array.
|
|
*
|
|
* \param network_data_tlv [IN] Network data TLV in byte array.
|
|
* \param network_data_tlv_length [IN] Length of the network data TLV byte array in bytes.
|
|
* \param service_tlv [IN] pointer to the previous Service TLV, NULL if previous TLV not known.
|
|
* [OUT] Pointer to the Service TLV found.
|
|
* \param stable [OUT] value set to true if found TLV is stable, false otherwise.
|
|
*
|
|
* \return Length of the found Service TLV
|
|
* \return 0 if TLV is empty or no Service TLV found.
|
|
* \return negative value indicates error in input parameters.
|
|
*/
|
|
int thread_border_router_service_tlv_find(uint8_t *network_data_tlv, uint16_t network_data_tlv_length, uint8_t **service_tlv, bool *stable);
|
|
|
|
/**
|
|
* Find Server TLV from the Network Data TLV (under Service TLV) byte array.
|
|
*
|
|
* \param service_tlv [IN] Network data TLV in byte array.
|
|
* \param service_tlv_length [IN] Length of the Network data TLV byte array in bytes.
|
|
* \param server_tlv [IN] pointer to the previous Server TLV, NULL if not known.
|
|
* [OUT] Pointer to the Server TLV found.
|
|
* \param stable [OUT] value set to true if found TLV is stable, false otherwise
|
|
*
|
|
* \return Length of the Prefix found
|
|
* \return 0 if TLV is empty or no TLV found.
|
|
* \return negative value indicates error in input parameters.
|
|
*/
|
|
int thread_border_router_server_tlv_find(uint8_t *service_tlv, uint16_t service_tlv_length, uint8_t **server_tlv, bool *stable);
|
|
|
|
/**
|
|
* Determine context ID from the Network Data TLV (under Prefix TLV) byte array.
|
|
*
|
|
* \param prefix_tlv [IN] Prefix TLV in byte array.
|
|
* \param prefix_tlv_length [IN] Length of the Prefix TLV byte array in bytes.
|
|
*
|
|
* \return The context ID value found
|
|
* \return -1 if error in input parameters.
|
|
* \return -2 if no context ID value found.
|
|
*/
|
|
int thread_border_router_prefix_context_id(uint8_t *prefix_tlv, uint16_t prefix_tlv_length);
|
|
|
|
/**
|
|
* Start mDNS responder service. The responder will respond to DNS-SD queries and send announcement when
|
|
* Thread network data is updated.
|
|
*
|
|
* The mDNS responder can be closed by calling thread_border_router_mdns_responder_stop(). Closing the Thread
|
|
* network interface will stop the mDNS responder automatically.
|
|
*
|
|
* \param interface_id interface ID of the Thread network
|
|
* \param interface_id_mdns interface where mDNS messaging occurs
|
|
* \param service_name mDNS instance name
|
|
*
|
|
* \return 0 on success
|
|
* \return <0 in case of errors
|
|
*
|
|
*/
|
|
int thread_border_router_mdns_responder_start(int8_t interface_id, int8_t interface_id_mdns, const char *service_name);
|
|
|
|
/**
|
|
* Stop mDNS responder service
|
|
*
|
|
* \return 0 on success
|
|
* \return <0 in case of errors
|
|
*
|
|
*/
|
|
int thread_border_router_mdns_responder_stop(void);
|
|
#endif /* THREAD_BORDER_ROUTER_API_H_ */
|