thread_management_client.h

00001 /*
00002  * Copyright (c) 2015-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  * 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 
00049 #define TRACE_GROUP_THREAD_MANAGEMENT_CLIENT "TMFs"
00050 
00051 /** Initialise thread management client.
00052  *
00053  * This instance needs to bee initialised once for each thread network interface.
00054  * if only one thread instance is supported this is needed to call only once.
00055  *
00056  * /param interface interface id of this thread instance.
00057  *
00058  */
00059 
00060 void thread_management_client_init(int8_t interface_id);
00061 
00062 /** Delete dhcp thread dhcp client.
00063  *
00064  * When this is called all addressed assigned by this module are removed from stack.
00065  */
00066 void thread_management_client_delete(int8_t interface_id);
00067 
00068 /** Get service id of management service.
00069  *
00070  * When using Coap Management port service this service is the only instance used to make client transactions.
00071  */
00072 int8_t thread_management_client_service_id_get(int8_t interface_id);
00073 
00074 /** Router id handler callback.
00075  *
00076  * callback to inform when new router id is received from leader.
00077  *
00078  *  /param status status of operation 0 success, -1 not accepted
00079  *  /param router_rloc router rloc16 address assigned to this device. 0xfffe if failure.
00080  *  /param router_mask_ptr Router id mask of current thread network.
00081  *
00082  */
00083 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]);
00084 
00085 /** request router id from the leader of network.
00086  *
00087  *  /param mac extented mac address of requested device.
00088  *  /param router_id old router id of this device, 0xffff if new address requested.
00089  *  /param id_cb callback to inform result of the request.
00090  *  /param status See thread 1.1.0 specification, chapter 5.19.5 for possible values.
00091  *
00092  * return positive value indicates COAP message ID of the request, zero or negative value indicates failure
00093  */
00094 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);
00095 
00096 /** release router id from the leader of network.
00097  *
00098  *  /param mac extented mac address of requested device.
00099  *  /param router_id router id of this device.
00100  *  /param id_cb callback to inform result of the request when calling this status is -1 and address is 0xfffe.
00101  *
00102  * return 0 success other values failure
00103  */
00104 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);
00105 
00106 /** Network data set response callback.
00107  *
00108  * callback to inform if network data was set to leader.
00109  *
00110  * /param status status of operation 0 success, -1 failure from leader received
00111  * /param data_ptr pointer to network data TLV that leader accepted.
00112  * /param data_len length of network data.
00113  *
00114  */
00115 typedef void thread_management_client_network_data_set_cb(int8_t interface_id, int8_t status, uint8_t *data_ptr, uint16_t data_len);
00116 
00117 /** send network data to leader of the network
00118  *
00119  * /param interface interface id of this thread instance.
00120  * /param data_ptr pointer to network data TLV to publish for leader of the network.
00121  * /param data_len length of network data.
00122  * /param set_cb callback to see if setting of network data was success. can be NULL.
00123  *
00124  *return 0 success other values failure
00125  */
00126 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);
00127 
00128 /** Send network data clear for leader to clean network data related to this rloc16.
00129  *
00130  * /param interface interface id of this thread instance.
00131  * /param rloc16 rloc16 of device which network data is unregistered.
00132  *
00133  *return 0 success other values failure
00134  */
00135 int thread_management_client_network_data_unregister(int8_t interface_id, uint16_t rloc16);
00136 
00137 /** Send neighbor discovery data request to given destination. Requested options will be:
00138  *  -Recursive DNS Server Option (25) and,
00139  *  -DNS Search List Option (31).
00140  *
00141  * /param interface interface id of this thread instance.
00142  * /param destination address where message is sent.
00143  * /param options requested nd data options according to RFC6106
00144  * /param options_len number of options requested
00145  * /param set_cb callback to be called when a response arrives.
00146  *
00147  *return 0 success other values failure
00148  */
00149 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);
00150 
00151 /** send active configuration dataset get for parent
00152  *
00153  * /param interface_id interface id of this thread instance.
00154  * /param dst_address destination address
00155  *
00156  *return 0 success other values failure
00157  */
00158 int8_t thread_management_client_active_get(int8_t interface_id, uint8_t *dst_address);
00159 
00160 /** send active configuration dataset set for parent
00161  *
00162  * /param interface_id interface id of this thread instance.
00163  * /param dst_address destination address
00164  *
00165  *return 0 success other values failure
00166  */
00167 int8_t thread_management_client_active_set(int8_t interface_id, uint8_t *dst_address);
00168 
00169 /** send pending configuration dataset get query for parent
00170  *
00171  * /param interface_id interface id of this thread instance.
00172  * /param dst_address destination address
00173  *
00174  *return 0 success other values failure
00175  */
00176 int8_t thread_management_client_pending_get(int8_t interface_id, uint8_t *dst_address);
00177 
00178 /** send next pending configuration dataset
00179  *
00180  * /param interface_id interface id of this thread instance.
00181  * /param dst_address destination address
00182  *
00183  *return 0 success other values failure
00184  */
00185 int8_t thread_management_client_pending_set(int8_t interface_id, uint8_t *dst_address);
00186 
00187 /** Send application provisioning message
00188  *
00189  * /param interface_id interface id of this thread instance.
00190  * /param dst_address destination address
00191  * /param port destination port
00192  *
00193  *return 0 success other values failure
00194  */
00195 int thread_management_client_provision_request(int8_t interface_id, uint8_t *dst_address, uint16_t port);
00196 
00197 /** Send out Address Notification proactively.
00198  *
00199  *  \param interface_id interface id of this Thread instance.
00200  *  \param address The target address added to the interface.
00201  *  \param rloc RLOC responsible for the target address.
00202  *  \param ml_eid Mesh-local EID value.
00203  *  \param dst_addr The address to send the notification to.
00204  */
00205 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]);
00206 
00207 /** Kill pending COAP requests.
00208  *
00209  *  \param interface_id interface id of this Thread instance.
00210  */
00211 void thread_management_client_pending_coap_request_kill(int8_t interface_id);
00212 #endif /* THREAD_MANAGEMENT_CLIENT_H_ */