thread_management_server.h

00001 /*
00002  * Copyright (c) 2014-2019, 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 server implementation.
00032  *
00033  * This server must be enabled for all devices in thread network.
00034  * Normal operation allows
00035  * - Thread diagnostic API
00036  * - Joiner router forwarding.
00037  *
00038  * Leader mode
00039  * Following additional services are required from the leader of Thread network
00040  * - Router id assignment server.
00041  * - Thread commissioning registration support
00042  * - Thread management command support
00043  * - thread network data handling support
00044  */
00045 
00046 
00047 #ifndef THREAD_MANAGEMENT_SERVER_H_
00048 #define THREAD_MANAGEMENT_SERVER_H_
00049 
00050 #ifdef __cplusplus
00051 extern "C" {
00052 #endif
00053 
00054 #include <ns_types.h>
00055 #include "thread_management_if.h"
00056 
00057 typedef struct thread_management_server_data {
00058     uint16_t joiner_router_port;
00059     uint16_t commissioner_port;
00060     bool joiner_router_enabled: 1;
00061 } thread_management_server_data_t;
00062 
00063 
00064 struct sn_coap_hdr_;
00065 
00066 /** initialise CoAP thread management server
00067  * This instance needs to be initialised for all thread devices.
00068  *
00069  * When this is initialised this will enable the default management functionality for all the nodes in thread network,.
00070  *
00071  * /param interface_id interface id of this thread instance.
00072  */
00073 int thread_management_server_init(int8_t interface_id);
00074 
00075 /** Delete thread management services.
00076  *
00077  * When this is called it close selected service and free all allocated memory.
00078  *
00079  *  /param interface interface id of this thread instance.
00080  */
00081 void thread_management_server_delete(int8_t interface_id);
00082 
00083 /** initialise Joiner router module
00084  *
00085  *  This is called when commissioner becomes present in network.
00086  *  This will open the listening port for joiner device and starts forwarding traffic to
00087  *  the commissioner device.
00088  *
00089  * /param interface interface id of this thread instance.
00090  *
00091  */
00092 int thread_management_server_joiner_router_init(int8_t interface_id);
00093 
00094 /** De-initialise Joiner router module
00095  *
00096  * Closes joiner router module.
00097  *
00098  * /param interface interface id of this thread instance.
00099  *
00100  */
00101 void thread_management_server_joiner_router_deinit(int8_t interface_id);
00102 
00103 /** Get service id of management service.
00104  *
00105  * When using Coap Management port service this service is the only instance used to make client transactions.
00106  */
00107 int8_t thread_management_server_service_id_get(int8_t interface_id);
00108 
00109 int8_t thread_management_server_interface_id_get(int8_t coap_service_id);
00110 
00111 int thread_management_server_commisoner_data_get(int8_t interface_id, thread_management_server_data_t *server_data);
00112 
00113 /**
00114  * Check if address can be found from network.
00115  *
00116  * \param interface_id
00117  * \param source_address
00118  *
00119  * \return true if address can be found from network, false otherwise.
00120  */
00121 bool thread_management_server_source_address_check(int8_t interface_id, uint8_t source_address[16]);
00122 
00123 /**
00124  * Handler for TMF GET-request messages:
00125  * -MGMT_GET (uri = /c/mg),
00126  * -MGMT_ACTIVE_GET (uri = /c/ag),
00127  * -MGMT_PENDING_GET (uri = /c/pg)
00128  *
00129  * \param interface_id
00130  * \param coap_service_id COAP service id
00131   * \param request_ptr COAP Request to handle
00132  *
00133  * \return 0 if response to request is send, negative value in case of error.
00134  */
00135 int thread_management_server_tmf_get_request_handler(int8_t interface_id, int8_t coap_service_id, struct sn_coap_hdr_ *request_ptr);
00136 
00137 #ifdef HAVE_THREAD_V2
00138 int thread_management_server_ccm_service_init(int8_t interface_id);
00139 #else
00140 #define thread_management_server_ccm_service_init(interface_id)
00141 #endif
00142 
00143 #ifdef __cplusplus
00144 }
00145 #endif
00146 
00147 #endif /* THREAD_MANAGEMENT_SERVER_H_ */