thread_management_client.h

00001 /*
00002  * Copyright (c) 2015-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  * Thread CoAP management client implementation.
00032  *
00033  * This client must be enabled for ROUTER, REED and HOST that want to publish network data.
00034  *
00035  * HOST
00036  * - sending own network data to thread leader
00037  *
00038  * REED
00039  * - Router id assignment client.
00040  */
00041 
00042 
00043 #ifndef THREAD_MANAGEMENT_CLIENT_H_
00044 #define THREAD_MANAGEMENT_CLIENT_H_
00045 
00046 #include <ns_types.h>
00047 #include "thread_management_if.h"
00048 #include "net_interface.h"
00049 
00050 #define TRACE_GROUP_THREAD_MANAGEMENT_CLIENT "TMFs"
00051 
00052 /** Initialise thread management client.
00053  *
00054  * This instance needs to bee initialised once for each thread network interface.
00055  * if only one thread instance is supported this is needed to call only once.
00056  *
00057  * /param interface interface id of this thread instance.
00058  *
00059  */
00060 
00061 void thread_management_client_init(int8_t interface_id);
00062 
00063 /** Delete dhcp thread dhcp client.
00064  *
00065  * When this is called all addressed assigned by this module are removed from stack.
00066  */
00067 void thread_management_client_delete(int8_t interface_id);
00068 
00069 /** Router id handler callback.
00070  *
00071  * callback to inform when new router id is received from leader.
00072  *
00073  *  /param status status of operation 0 success, -1 not accepted
00074  *  /param router_rloc router rloc16 address assigned to this device. 0xfffe if failure.
00075  *  /param router_mask_ptr Router id mask of current thread network.
00076  *
00077  */
00078 typedef void thread_management_client_router_id_cb(int8_t interface_id, int8_t status, uint16_t router_rloc, const uint8_t router_mask_ptr[9]);
00079 
00080 /** request router id from the leader of network.
00081  *
00082  *  /param mac extented mac address of requested device.
00083  *  /param router_id old router id of this device, 0xffff if new address requested.
00084  *  /param id_cb callback to inform result of the request.
00085  *  /param status See thread 1.1.0 specification, chapter 5.19.5 for possible values.
00086  *
00087  * return positive value indicates COAP message ID of the request, zero or negative value indicates failure
00088  */
00089 int thread_management_client_router_id_get(int8_t interface_id, uint8_t mac[8], uint16_t router_id, thread_management_client_router_id_cb *id_cb, uint8_t status);
00090 
00091 /** release router id from the leader of network.
00092  *
00093  *  /param mac extented mac address of requested device.
00094  *  /param router_id router id of this device.
00095  *  /param id_cb callback to inform result of the request when calling this status is -1 and address is 0xfffe.
00096  *
00097  * return 0 success other values failure
00098  */
00099 int thread_management_client_router_id_release(int8_t interface_id, uint8_t mac[8], uint16_t router_id, thread_management_client_router_id_cb *id_cb);
00100 
00101 /** Network data set response callback.
00102  *
00103  * callback to inform if network data was set to leader.
00104  *
00105  * /param status status of operation 0 success, -1 failure from leader received
00106  * /param data_ptr pointer to network data TLV that leader accepted.
00107  * /param data_len length of network data.
00108  *
00109  */
00110 typedef void thread_management_client_network_data_set_cb(int8_t interface_id, int8_t status, uint8_t *data_ptr, uint16_t data_len);
00111 
00112 /** send network data to leader of the network
00113  *
00114  * /param interface interface id of this thread instance.
00115  * /param data_ptr pointer to network data TLV to publish for leader of the network.
00116  * /param data_len length of network data.
00117  * /param set_cb callback to see if setting of network data was success. can be NULL.
00118  *
00119  *return 0 success other values failure
00120  */
00121 int thread_management_client_network_data_register(int8_t interface_id, uint8_t *data_ptr, uint16_t data_len, thread_management_client_network_data_set_cb *set_cb);
00122 
00123 /** Send network data clear for leader to clean network data related to this rloc16.
00124  *
00125  * /param interface interface id of this thread instance.
00126  * /param rloc16 rloc16 of device which network data is unregistered.
00127  *
00128  *return 0 success other values failure
00129  */
00130 int thread_management_client_network_data_unregister(int8_t interface_id, uint16_t rloc16);
00131 
00132 /** Send neighbor discovery data request to given destination. Requested options will be:
00133  *  -Recursive DNS Server Option (25) and,
00134  *  -DNS Search List Option (31).
00135  *
00136  * /param interface interface id of this thread instance.
00137  * /param destination address where message is sent.
00138  * /param options requested nd data options according to RFC6106
00139  * /param options_len number of options requested
00140  * /param set_cb callback to be called when a response arrives.
00141  *
00142  *return 0 success other values failure
00143  */
00144 int thread_management_client_neighbor_discovery_data_request(int8_t interface_id, const uint8_t destination[16],  const uint8_t *options, uint8_t options_len, thread_management_client_network_data_set_cb *set_cb);
00145 
00146 /** Get interface_id of based on coap service_id
00147  *
00148  *
00149  * /param service_id coap service id.
00150  *
00151  *return interface_id of thread instance if successful and -1 for failure
00152  */
00153 int thread_management_client_get_interface_id_by_service_id(int8_t service_id);
00154 
00155 /** send active configuration dataset get for parent
00156  *
00157  * /param interface_id interface id of this thread instance.
00158  * /param dst_address destination address
00159  *
00160  *return 0 success other values failure
00161  */
00162 int8_t thread_management_client_active_get(int8_t interface_id, uint8_t *dst_address);
00163 
00164 /** send active configuration dataset set for parent
00165  *
00166  * /param interface_id interface id of this thread instance.
00167  * /param dst_address destination address
00168  *
00169  *return 0 success other values failure
00170  */
00171 int8_t thread_management_client_active_set(int8_t interface_id, uint8_t *dst_address);
00172 
00173 /** send pending configuration dataset get query for parent
00174  *
00175  * /param interface_id interface id of this thread instance.
00176  * /param dst_address destination address
00177  *
00178  *return 0 success other values failure
00179  */
00180 int8_t thread_management_client_pending_get(int8_t interface_id, uint8_t *dst_address);
00181 
00182 /** send next pending configuration dataset
00183  *
00184  * /param interface_id interface id of this thread instance.
00185  * /param dst_address destination address
00186  *
00187  *return 0 success other values failure
00188  */
00189 int8_t thread_management_client_pending_set(int8_t interface_id, uint8_t *dst_address);
00190 
00191 /** Send application provisioning message
00192  *
00193  * /param interface_id interface id of this thread instance.
00194  * /param dst_address destination address
00195  * /param port destination port
00196  *
00197  *return 0 success other values failure
00198  */
00199 int thread_management_client_provision_request(int8_t interface_id, uint8_t *dst_address, uint16_t port);
00200 
00201 /** Send out Address Notification proactively.
00202  *
00203  *  \param interface_id interface id of this Thread instance.
00204  *  \param address The target address added to the interface.
00205  *  \param rloc RLOC responsible for the target address.
00206  *  \param ml_eid Mesh-local EID value.
00207  *  \param dst_addr The address to send the notification to.
00208  */
00209 void thread_management_client_proactive_an(int8_t interface_id, const uint8_t address[16], const uint16_t rloc, const uint8_t ml_eid[8], const uint8_t dst_addr[16]);
00210 
00211 /** Delete COAP message .
00212  *
00213  * Delete COAP message that is sent to COAP service.
00214  *
00215  *  \param interface_id interface id of this Thread instance.
00216  *  \param coap_message_id COAP message to be deleted.
00217  */
00218 void thread_management_client_coap_message_delete(int8_t interface_id, uint16_t coap_message_id);
00219 
00220 /** Clear old partition data.
00221  *
00222  * Clear data related to old partition, like pending COAP transactions.
00223  *
00224  *  \param interface_id interface id of this Thread instance.
00225  */
00226 void thread_management_client_old_partition_data_clean(int8_t interface_id);
00227 
00228 #ifdef HAVE_THREAD_V2
00229 /** Send address notification message.
00230  *
00231  * Sends address notification message
00232  *
00233  *  \param interface_id interface id of this Thread instance.
00234  */
00235 void thread_management_client_addr_ntf_send(int8_t interface_id, uint8_t *destination_address, const uint8_t *addr_data_ptr, uint8_t bbr_status);
00236 /** Send multicast registration message
00237  *
00238  * include all the addresses that are registered to the bbr
00239  *
00240  *  \param interface_id interface id of this Thread instance.
00241  */
00242 int thread_management_client_mlr_req_send(int8_t interface_id, const uint8_t br_addr[16], const uint8_t *address, uint8_t address_len);
00243 #else
00244 
00245 #define thread_management_client_addr_ntf_send(interface_id, destination_address, addr_data_ptr, bbr_status) (void(0))
00246 #define thread_management_client_mlr_req_send(interface_id, br_addr, address, address_len) (void(0))
00247 #endif
00248 
00249 
00250 #endif /* THREAD_MANAGEMENT_CLIENT_H_ */