thread_management_api.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  * \file thread_management_api.h
00032  * \brief Public API for managing Thread network configuration.
00033  *
00034  * This interface enables modification and reading the Thread network parameters.
00035  *
00036  * Thread management can modify the following values in the Thread network:
00037  * * [Network Name] (Read/write)
00038  * * [Security Policy] (Read/write)
00039  * * [Steering Data] (Read/write)
00040  * * [Commissioning Data Timestamp] (Read/write)
00041  * * [Commissioning Credential] PSKc (Write only)
00042  * * [Network Master Key] (Read only when policy allows)
00043  * * [Network Key Sequence] (Read only when policy allows)
00044  * * [Network Mesh-Local ULA] (Read only)
00045  * * [Border Router Locator] (Read only)
00046  * * [Commissioner Session ID] (Read only)
00047  * * [XPANID] (Read only)
00048  * * [PANID] (Read only)
00049  * * [Channel] (Read only)
00050  */
00051 
00052 #ifndef THREAD_MANAGEMENT_API_H_
00053 #define THREAD_MANAGEMENT_API_H_
00054 
00055 #ifdef __cplusplus
00056 extern "C" {
00057 #endif
00058 
00059 #include "ns_types.h"
00060 
00061 #define TRACE_GROUP_THREAD_MANAGEMENT_API "TMaA"  /**< trace group definition */
00062 
00063 /** Thread management state
00064  */
00065 typedef enum {
00066     MANAGEMENT_STATE_REJECT,
00067     MANAGEMENT_STATE_PENDING,
00068     MANAGEMENT_STATE_ACCEPT
00069 } management_state_e;
00070 
00071 /** \brief Register Thread management interface
00072  *
00073  * \param interface_id Interface ID of the Thread network.
00074  *
00075  * \return A handle for the management interface.
00076  *
00077  */
00078 int thread_management_register(int8_t interface_id);
00079 
00080 /** \brief Unregister Thread management interface
00081  *
00082  * \param instance_id ID of the management session.
00083  *
00084  */
00085 int thread_management_unregister(int8_t instance_id);
00086 
00087 /** \brief Callback to display the result of management set command.
00088  *
00089  * This callback is called when the server responds to the management set command.
00090  * This can fail if the leader rejects the request or the request times out.
00091  *
00092  * \param interface_id The interface ID of the Thread network.
00093  * \param status Result of the request.
00094  *
00095  */
00096 typedef int (management_set_response_cb)(int8_t interface_id, management_state_e status);
00097 
00098 /** \brief Set the Thread security policy
00099 *
00100 * \param instance_id The ID of the management session.
00101 * \param options Security policy options:
00102 *    bit 8 Out-of-band commissioning restricted.
00103 *    bit 7 Native commissioner restricted.
00104 * \param rotation_time Thread key rotation time in hours.
00105 * \param cb_ptr A callback function indicating the result of the operation. Can be NULL if no result code needed.
00106 *
00107 * \return 0 Success.
00108 * \return <0 Fail.
00109 */
00110 int thread_management_set_security_policy(int8_t instance_id, uint8_t options, uint16_t rotation_time, management_set_response_cb *cb_ptr);
00111 
00112 /** \brief Set the steering data
00113  *
00114  * Steering data can be either:
00115  *  - Empty to decline joining.
00116  *  - Any length with all bits set to 0 to decline joining.
00117  *  - Any length with all bits 1 to allow anyone to join.
00118  *  - Bloom filter to guide which device can join.
00119  *
00120  * If a Bloom filter is present it can be any length between 1-16 bytes. The first bit of the Bloom
00121  * filter indicates whether to use 0 == EUI-64 or 1 == bottom 24 bits of EUI-64.
00122  *
00123  * \param instance_id The ID of the management session.
00124  * \param session_id The commissioning session ID that needs to be added.
00125  * \param steering_data_ptr A pointer to new steering data.
00126  * \param steering_data_len The length of the new steering data.
00127  * \param cb_ptr A callback function indicating the result of the operation. Can be NULL if no result code needed.
00128  *
00129  * \return 0 Success.
00130  * \return <0 Fail.
00131  */
00132 int thread_management_set_steering_data(int8_t instance_id, uint16_t session_id, uint8_t *steering_data_ptr, uint8_t steering_data_len, management_set_response_cb *cb_ptr);
00133 
00134 /** \brief Set the Thread commissioning data timestamp
00135  *
00136  * \param instance_id The ID of the management session.
00137  * \param time Upper 48 bits is the timestamp in seconds since the start of unix time, lower 16 bits are fractional portion of time. If the last bit is set to 1, the commissioner has accurate time.
00138  * \param cb_ptr A callback function indicating the result of the operation. Can be NULL if no result code needed.
00139  *
00140  * \return 0 Success.
00141  * \return <0 Fail.
00142  */
00143 int thread_management_set_commissioning_data_timestamp(int8_t instance_id, uint64_t time, management_set_response_cb *cb_ptr);
00144 
00145 /** \brief Callback for reading Thread management information
00146  *
00147  * Result message containing the Thread management TLV message.
00148  * This message can be parsed with thread_meshcop_lib.h.
00149  *
00150  * \param instance_id The ID of the management session.
00151  * \param status Result of the request.
00152  * \param response_message_ptr A meshcop TLV structure pointer containing the requested TLVs.
00153  * \param response_message_len The length of the message.
00154  *
00155  * \return 0 Success.
00156  * \return <0 Fail.
00157  */
00158 typedef int (management_get_response_cb)(int8_t instance_id, management_state_e status, uint8_t *response_message_ptr, uint16_t response_message_len);
00159 
00160 /** \brief Get Thread management fields.
00161  * Fetching Thread management field values from any device in the Thread network.
00162  *
00163  * \param instance_id Instance ID of the management session.
00164  * \param dst_addr Destination address; the address of a remote device from whome it is desirable to fetch  management information. If however, the address is not provided, a request is sent to the leader of the network for this purpose. If a native commissioner is used, the request for management information is sent to the border router.
00165  * \param uri_ptr The ASCII string for the URI. This string identifies the CoAP URI for the desired resource. For example, /c/mg identifies the management get information resource.
00166  * \param fields_ptr A pointer that points to an array of desirable MESHCOP TLVs. A list of such TLVs can be found in thread_meshcop_lib.h
00167  * \param fields_count Number of fields in the field pointer array (set of TLVs).
00168  * \param cb_ptr A callback function carrying the result of the operation.
00169  *
00170  * \return 0, Success.
00171  * \return <0 Fail.
00172  */
00173 int thread_management_get(int8_t instance_id, uint8_t dst_addr[static 16], char *uri_ptr, uint8_t *fields_ptr, uint8_t fields_count, management_get_response_cb *cb_ptr);
00174 
00175 /** \brief Set Thread management fields
00176  *
00177  * Set Thread management field values to a device in Thread network.
00178  *
00179  * \param instance_id Instance ID of the management session.
00180  * \param dst_addr Destination address, the address of a remote device where it is desired to setup management information. If however, the address is not provided, a request is sent to leader of the network for this purpose. If a  native commissioner is being used, the rquest for setting up management information is sent to the Border router.
00181  * \param uri_ptr The ASCII string for the URI. This string identifies the CoAP URI for the desired resource, for example, /c/ms identifies the the management set information resource.
00182  * \param data_ptr A pointer to the desired set of TLVs.
00183  * \param data_len count of the members (no. of TLVs) in the TLV set.
00184  * \param cb_ptr A callback function carrying the result of the operation.
00185  *
00186  * \return 0, Success
00187  * \return <0 Fail.
00188  *
00189  */
00190 int thread_management_set(int8_t instance_id, uint8_t dst_addr[static 16], char *uri_ptr, uint8_t *data_ptr, uint8_t data_len, management_set_response_cb *cb_ptr);
00191 
00192 #ifdef __cplusplus
00193 }
00194 #endif
00195 #endif /* THREAD_MANAGEMENT_API_H_ */