thread_resolution_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 address resolution client implementation.
00032  *
00033  * This client must be enabled for ROUTER, REED and non-sleepy HOST.
00034  *
00035  */
00036 
00037 
00038 #ifndef THREAD_RESOLUTION_CLIENT_H_
00039 #define THREAD_RESOLUTION_CLIENT_H_
00040 #include <ns_types.h>
00041 
00042 #define TRACE_GROUP_THREAD_RESOLUTION_CLIENT "TRsC"
00043 
00044 /** Notification callback.
00045  *
00046  * callback to inform when unsolicited notification is received
00047  *
00048  *  \param interface_id interface id of thread instance
00049  *  \param ip_addr IP address from response
00050  *  \param loc_addr 16-bit "RLOC" address from response
00051  *  \param ml_eid 64-bit extended MAC address from response
00052  */
00053 typedef void thread_resolution_client_notification_cb(int8_t interface_id, const uint8_t ip_addr[16], uint16_t loc_addr, const uint8_t ml_eid[8]);
00054 
00055 /** Resolution response callback.
00056  *
00057  * callback to inform when response to resolution is received
00058  *
00059  *  \param interface_id interface id of thread instance
00060  *  \param status status of operation 0 success, -1 failed
00061  *  \param ip_addr IP address from response
00062  *  \param loc_addr 16-bit "RLOC" address from response
00063  *  \param last_transaction_time last transaction time from response; 0 if not present
00064  *  \param mleid Target MLEID
00065  *
00066  */
00067 typedef void thread_resolution_client_response_cb(int8_t interface_id, int8_t status, const uint8_t ip_addr[16], uint16_t loc_addr, uint32_t last_transaction_time, uint8_t *mleid);
00068 
00069 /** Error callback.
00070  *
00071  * callback to inform when address error is received
00072  *
00073  *  \param interface_id interface id of thread instance
00074  *  \param ip_addr target IP address from error
00075  *  \param ml_eid 64-bit ML-EID from error
00076  */
00077 typedef void thread_resolution_client_error_cb(int8_t interface_id, const uint8_t ip_addr[16], const uint8_t ml_eid[8]);
00078 
00079 #ifdef HAVE_THREAD_NEIGHBOR_DISCOVERY
00080 
00081 /** Initialise thread resolution client.
00082  *
00083  * This instance needs to be initialised once for each thread network interface.
00084  * if only one thread instance is supported this is needed to call only once.
00085  *
00086  * \param interface_id interface id of this thread instance.
00087  */
00088 
00089 void thread_resolution_client_init(int8_t interface_id);
00090 
00091 /** Delete Thread resolution client.
00092  *
00093  * \param interface_id interface id of this thread instance.
00094  */
00095 void thread_resolution_client_delete(int8_t interface_id);
00096 
00097 
00098 /** Set callback pointer for notifications
00099  *
00100  *  \param interface_id interface id of this thread instance.
00101  *  \param notification_cb callback function
00102  */
00103 void thread_resolution_client_set_notification_cb(int8_t interface_id, thread_resolution_client_notification_cb notification_cb);
00104 
00105 /** Set callback pointer for errors
00106  *
00107  *  \param interface_id interface id of this thread instance.
00108  *  \param error_cb callback function
00109  */
00110 void thread_resolution_client_set_error_cb(int8_t interface_id, thread_resolution_client_error_cb error_cb);
00111 
00112 /** Initiate address resolution
00113  *
00114  * Intent is that this API should ultimately implement collation of multiple
00115  * replies and selection by time indicators, and it should also implement the
00116  * "retry delay" blockage.
00117  *
00118  * Initial implementation will just be a direct shim to CoAP, and return every
00119  * POSTed response.
00120  *
00121  * \note The callback sets a per-instance callback pointer; it's not possible
00122  * to have different callbacks for multiple ongoing resolutions. Indeed, there
00123  * is currently no transaction state.
00124  *
00125  *  \param interface_id interface id of this thread instance.
00126  *  \param ip_addr IP address to resolve
00127  *  \param resp_cb callback to inform result of the request.
00128  *
00129  * return 0 success (resolution in progress), -1 failure
00130  */
00131 int thread_resolution_client_resolve(int8_t interface_id, uint8_t ip_addr[16], thread_resolution_client_response_cb *resp_cb);
00132 
00133 /** Send an address error message
00134  *
00135  * \param interface_id interface id of this thread instance.
00136  * \param dest_ip_addr address to send error message (unicast or multicast)
00137  * \param target_ip_addr target IP address that is in error
00138  * \param ml_eid ML-EID for error report (routers with different ML-EID are in error)
00139  */
00140 int thread_resolution_client_address_error(int8_t interface_id, const uint8_t dest_ip_addr[16], const uint8_t target_ip_addr[16], const uint8_t ml_eid[8]);
00141 
00142 /** Periodic timer
00143  *
00144  * Called to maintain address query set.
00145  *
00146  * \param interface_id interface id of this thread instance.
00147  * \param seconds number of seconds elapsed since last call (usually 1)
00148  */
00149 void thread_resolution_client_timer(int8_t interface_id, uint16_t seconds);
00150 
00151 #else //HAVE_THREAD_NEIGHBOR_DISCOVERY
00152 
00153 #define thread_resolution_client_init(interface_id)
00154 #define thread_resolution_client_delete(interface_id)
00155 #define thread_resolution_client_set_notification_cb(interface_id, notification_cb)
00156 #define thread_resolution_client_set_error_cb(interface_id, error_cb)
00157 #define thread_resolution_client_resolve(interface_id, ip_addr, resp_cb) (-1)
00158 #define thread_resolution_client_address_error(interface_id, dest_ip_addr, target_ip_addr, ml_eid)
00159 #define thread_resolution_client_timer(interface_id, seconds)
00160 
00161 #endif //HAVE_THREAD_NEIGHBOR_DISCOVERY
00162 
00163 #endif /* THREAD_RESOLUTION_CLIENT_H_ */