/*
 * 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_ */