git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-IoT-Libraries/abstractions/platform/include/platform/iot_metrics.h

   1 /*\r
   2  * Amazon FreeRTOS Platform V1.0.0\r
   3  * Copyright (C) 2019 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  *\r
  22  * http://aws.amazon.com/freertos\r
  23  * http://www.FreeRTOS.org\r
  24  */\r
  25 \r
  26 /**\r
  27  * @file iot_metrics.h\r
  28  * @brief Functions for retrieving [Device Defender](@ref defender) metrics.\r
  29  *\r
  30  * The functions in this header are only required by Device Defender. They do not\r
  31  * need to be implemented if Device Defender is not used.\r
  32  */\r
  33 \r
  34 #ifndef IOT_METRICS_H_\r
  35 #define IOT_METRICS_H_\r
  36 \r
  37 /* The config header is always included first. */\r
  38 #include "iot_config.h"\r
  39 \r
  40 /* Standard includes. */\r
  41 #include <stdbool.h>\r
  42 \r
  43 /* Linear containers (lists and queues) include. */\r
  44 #include "iot_linear_containers.h"\r
  45 \r
  46 /**\r
  47  * @functionspage{platform_metrics,platform metrics component,Metrics}\r
  48  * - @functionname{platform_metrics_function_init}\r
  49  * - @functionname{platform_metrics_function_cleanup}\r
  50  * - @functionname{platform_metrics_function_gettcpconnections}\r
  51  */\r
  52 \r
  53 /**\r
  54  * @functionpage{IotMetrics_Init,platform_metrics,init}\r
  55  * @functionpage{IotMetrics_Cleanup,platform_metrics,cleanup}\r
  56  * @functionpage{IotMetrics_GetTcpConnections,platform_metrics,gettcpconnections}\r
  57  */\r
  58 \r
  59 /**\r
  60  * @brief One-time initialization function for the platform metrics component.\r
  61  *\r
  62  * This function initializes the platform metrics component. <b>It must be called\r
  63  * once (and only once) before calling any other metrics or [Device Defender function]\r
  64  * (@ref defender_functions).</b> Calling this function more than once without first\r
  65  * calling @ref platform_metrics_function_cleanup may result in a crash.\r
  66  *\r
  67  * @return `true` is initialization succeeded; `false` otherwise.\r
  68  *\r
  69  * @warning No thread-safety guarantees are provided for this function.\r
  70  */\r
  71 /* @[declare_platform_metrics_init] */\r
  72 bool IotMetrics_Init( void );\r
  73 /* @[declare_platform_metrics_init] */\r
  74 \r
  75 /**\r
  76  * @brief One-time deinitialization function for the platform metrics component.\r
  77  *\r
  78  * This function frees resources taken in @ref platform_metrics_function_init.\r
  79  * No other metrics or [Device Defender functions](@ref defender_functions) may\r
  80  * be called unless @ref platform_metrics_function_init is called again.\r
  81  *\r
  82  * @warning No thread-safety guarantees are provided for this function.\r
  83  */\r
  84 /* @[declare_platform_metrics_cleanup] */\r
  85 void IotMetrics_Cleanup( void );\r
  86 /* @[declare_platform_metrics_cleanup] */\r
  87 \r
  88 /**\r
  89  * @brief Retrieve a list of active TCP connections from the system.\r
  90  *\r
  91  * The provided connections are reported by Device Defender.\r
  92  *\r
  93  * @param[in] pContext Context passed as the first parameter of `metricsCallback`.\r
  94  * @param[in] metricsCallback Called by this function to provide the list of TCP\r
  95  * connections. The list given by this function is should not be used after the\r
  96  * callback returns.\r
  97  */\r
  98 /* @[declare_platform_metrics_gettcpconnections] */\r
  99 void IotMetrics_GetTcpConnections( void * pContext,\r
 100                                    void ( * metricsCallback )( void *, const IotListDouble_t * ) );\r
 101 /* @[declare_platform_metrics_gettcpconnections] */\r
 102 \r
 103 #endif /* ifndef IOT_METRICS_H_ */\r