thread_leader_service.h

00001 /*
00002  * Copyright (c) 2016-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  * \brief Nanostack Thread leader service. Service is responsible of Leader specific
00032  * tasks like:
00033  * -Router ID assignment
00034  * -Partitioning
00035  * -Leader TLV writing
00036  * -Leader COAP message handling
00037  */
00038 
00039 #ifndef _THREAD_LEADER_SERVICE_H_
00040 #define _THREAD_LEADER_SERVICE_H_
00041 #ifdef HAVE_THREAD_LEADER_SERVICE
00042 
00043 #include "MLE/mle_tlv.h"
00044 
00045 /** Initialize Thread Leader Service
00046  *
00047  * \param interface interface id of this thread instance.
00048  * \param coap_service_id assigned COAP service id to use
00049  *
00050  * \return 0 for success, negative value for error
00051  */
00052 int thread_leader_service_init(int8_t interface_id, uint8_t coap_service_id);
00053 
00054 /** Delete Thread Leader Service
00055  *
00056  * \param interface interface id of this thread instance.
00057  */
00058 void thread_leader_service_delete(int8_t interface_id);
00059 
00060 /** Start and initialise CoAP thread leader.
00061  *  When becoming a leader this method enables all the leader management functionalities using Thread management CoAP.
00062  *
00063  * \param interface interface id of this thread instance.
00064  * \param assign_cb callback for router id assignment request.
00065  * \param release_cb callback for router id release request.
00066  *
00067  * \return 0 for success, negative value in case of error
00068  *
00069  */
00070 int thread_leader_service_start(int8_t interface_id);
00071 
00072 /** Stop Thread leader service and return to normal device mode.
00073  *  This closes the leader functionality services from CoAP, but leaves the normal node behavior.
00074  *
00075  * \param interface interface id of this thread instance.
00076  *
00077  */
00078 void thread_leader_service_stop(int8_t interface_id);
00079 
00080 /** Free Thread leader data
00081  *
00082  * \param thread_info
00083  */
00084 void thread_leader_service_leader_data_free(struct thread_info_s *thread_info);
00085 
00086 /** Generate new Thread partition
00087  *
00088  * \param interface_id current interface
00089  * \param newPartition true if new partition is needed
00090  */
00091 void thread_leader_service_thread_partitition_generate(int8_t interface_id, bool newPartition);
00092 
00093 /** Start Leader after sync
00094  *
00095  * \param interface_id current interface
00096  * \param routing routing info used to rebuild
00097  */
00098 int thread_leader_service_thread_partitition_restart(int8_t interface_id, mle_tlv_info_t *routing);
00099 
00100 /** Update ID
00101  *
00102  * \param cur current interface
00103  */
00104 void thread_leader_service_update_id_set(protocol_interface_info_entry_t *cur);
00105 
00106 /** Generate new Thread partition
00107  *
00108  * \param cur current interface
00109  * \param tickUpdate ticks
00110  */
00111 void thread_leader_service_router_id_valid_lifetime_update(protocol_interface_info_entry_t *cur, uint32_t tickUpdate);
00112 
00113 bool thread_leader_service_route_mask_bit_clear(thread_leader_info_t *info, uint8_t router_id);
00114 
00115 void thread_leader_service_generate_network_data(protocol_interface_info_entry_t *cur);
00116 
00117 void thread_leader_service_network_data_changed(protocol_interface_info_entry_t *cur, bool force_stable_update, bool force_unstable_update);
00118 
00119 void thread_leader_service_timer(protocol_interface_info_entry_t *cur, uint32_t ticks);
00120 
00121 /** Get first child ID from network data based on parent ID
00122  *
00123  * \param thread_info
00124  * \param router_id router short address
00125  *
00126  * \return First child ID of the router children. 0 if no child found.
00127  */
00128 uint16_t thread_leader_service_child_id_from_networkdata_get(struct thread_info_s *thread_info, uint16_t router_short_addr);
00129 
00130 void thread_leader_service_router_state_changed(thread_info_t *thread_info, uint8_t router_id, bool available, int8_t interface_id);
00131 
00132 #else
00133 
00134 #define thread_leader_service_init(interface_id, coap_service_id) (0)
00135 
00136 #define thread_leader_service_delete(interface_id)
00137 
00138 #define thread_leader_service_start(interface_id) (-1)
00139 
00140 #define thread_leader_service_stop(interface_id)
00141 
00142 #define thread_leader_service_leader_data_free(thread_info)
00143 
00144 #define thread_leader_service_thread_partitition_generate(interface_id,newPartition)
00145 
00146 #define thread_leader_service_thread_partitition_restart(interface_id, routing) (-1)
00147 
00148 #define thread_leader_service_update_id_set(cur);
00149 
00150 #define thread_leader_service_router_id_valid_lifetime_update(cur,tickUpdate)
00151 
00152 #define thread_leader_service_route_mask_bit_clear(info,router_id) false
00153 
00154 #define thread_leader_service_generate_network_data(cur)
00155 
00156 #define thread_leader_service_network_data_changed(cur, force_stable_update, force_unstable_update)
00157 
00158 #define thread_leader_service_timer(cur,ticks)
00159 
00160 #define thread_leader_service_child_id_from_networkdata_get(thread_info,router_short_addr)
00161 
00162 #define thread_leader_service_router_state_changed(thread_info, router_id, available, interface_id)
00163 
00164 #endif /*HAVE_THREAD_LEADER_SERVICE*/
00165 
00166 #endif /* _THREAD_LEADER_SERVICE_H_ */