thread_lowpower_api.h

00001 /*
00002  * Copyright (c) 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  * \file thread_lowpower_api.h
00032  * \brief Nanostack Thread lowpower probe implementation. Responsible for tasks like
00033  * request link metrics by sending data requests.
00034  */
00035 
00036 #ifndef THREAD_LOWPOWER_API_H_
00037 #define THREAD_LOWPOWER_API_H_
00038 
00039 #include <ns_types.h>
00040 
00041 /** \brief callback function that returns the received metrics
00042  *
00043  * \param destination_address address to which the lowpower query is sent
00044  * \param interface_id interface_id of destination
00045  * \param metrics_ptr Pointer to metrics
00046  * \param metrics_len Length of metrics_ptr
00047  *
00048  * \return metrics_ptr if response received, NULL if no response is received
00049  * \return metrics_len length of the response received, 0 if NULL response is received
00050  *
00051  */
00052 typedef int (thread_lowpower_resp_cb)(uint8_t *destination_address, int8_t interface_id, uint8_t *metrics_ptr, uint16_t metrics_len);
00053 
00054 /** \brief Send lowpower data request for requesting low power metrics
00055  *
00056  * \param interface_id Interface ID of the Thread network.
00057  * \param address destination ll64 address
00058  * \param series_id id of the query or series id
00059  * \param series_flags query type 0 for single probe
00060  * \param timeout Timeout for the query 0 for single probe
00061  * \param metrics_ptr array of metrics to be measured
00062  * \param metrics_len length of the metrics array
00063  * \param response_cb callback function called to return values after execution
00064  *
00065  * \return 0 if data request successfully initiated.
00066  *
00067  */
00068 int thread_lowpower_metrics_management_request_send(int8_t interface_id, uint8_t *address, uint8_t series_id, uint8_t series_flags, uint16_t timeout,  uint8_t *metrics_ptr, uint8_t metrics_len, thread_lowpower_resp_cb response_cb);
00069 
00070 /** \brief DEPRECATED Send lowpower data request for requesting low power metrics
00071  *
00072  * use thread_lowpower_metrics_management_request_send instead
00073  * \param interface_id Interface ID of the Thread network.
00074  * \param destination_address destination ll64 address
00075  * \param metrics_ptr array of metrics to be measured
00076  * \param metrics_len length of the metrics array
00077  * \param response_cb callback function called to return values after execution
00078  *
00079  * \return 0 if data request successfully initiated.
00080  *
00081  */
00082 int thread_lowpower_test_probe_send(int8_t interface_id, uint8_t *destination_address, uint8_t *metrics_ptr, uint8_t metrics_len, thread_lowpower_resp_cb response_cb);
00083 
00084 #endif /*THREAD_LOWPOWER_API_H_ */