git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-IoT-Libraries/c_sdk/standard/common/include/private/iot_logging.h

   1 /*\r
   2  * Amazon FreeRTOS Common V1.0.0\r
   3  * Copyright (C) 2018 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_logging.h\r
  28  * @brief Generic logging function header file.\r
  29  *\r
  30  * Declares the generic logging function and the log levels. This file never\r
  31  * needs to be included in source code. The header iot_logging_setup.h should\r
  32  * be included instead.\r
  33  *\r
  34  * @see iot_logging_setup.h\r
  35  */\r
  36 \r
  37 #ifndef IOT_LOGGING_H_\r
  38 #define IOT_LOGGING_H_\r
  39 \r
  40 /* The config header is always included first. */\r
  41 #include "iot_config.h"\r
  42 \r
  43 /* Standard includes. */\r
  44 #include <stdbool.h>\r
  45 #include <stddef.h>\r
  46 #include <stdint.h>\r
  47 \r
  48 /**\r
  49  * @constantspage{logging,logging library}\r
  50  *\r
  51  * @section logging_constants_levels Log levels\r
  52  * @brief Log levels for the libraries in this SDK.\r
  53  *\r
  54  * Each library should specify a log level by setting @ref LIBRARY_LOG_LEVEL.\r
  55  * All log messages with a level at or below the specified level will be printed\r
  56  * for that library.\r
  57  *\r
  58  * Currently, there are 4 log levels. In the order of lowest to highest, they are:\r
  59  * - #IOT_LOG_NONE <br>\r
  60  *   @copybrief IOT_LOG_NONE\r
  61  * - #IOT_LOG_ERROR <br>\r
  62  *   @copybrief IOT_LOG_ERROR\r
  63  * - #IOT_LOG_WARN <br>\r
  64  *   @copybrief IOT_LOG_WARN\r
  65  * - #IOT_LOG_INFO <br>\r
  66  *   @copybrief IOT_LOG_INFO\r
  67  * - #IOT_LOG_DEBUG <br>\r
  68  *   @copybrief IOT_LOG_DEBUG\r
  69  */\r
  70 \r
  71 /**\r
  72  * @brief No log messages.\r
  73  *\r
  74  * Log messages with this level will be silently discarded. When @ref\r
  75  * LIBRARY_LOG_LEVEL is #IOT_LOG_NONE, logging is disabled and no [logging functions]\r
  76  * (@ref logging_functions) can be called.\r
  77  */\r
  78 #define IOT_LOG_NONE     0\r
  79 \r
  80 /**\r
  81  * @brief Only critical, unrecoverable errors.\r
  82  *\r
  83  * Log messages with this level will be printed when a library encounters an\r
  84  * error from which it cannot easily recover.\r
  85  */\r
  86 #define IOT_LOG_ERROR    1\r
  87 \r
  88 /**\r
  89  * @brief Message about an abnormal but recoverable event.\r
  90  *\r
  91  * Log messages with this level will be printed when a library encounters an\r
  92  * abnormal event that may be indicative of an error. Libraries should continue\r
  93  * execution after logging a warning.\r
  94  */\r
  95 #define IOT_LOG_WARN     2\r
  96 \r
  97 /**\r
  98  * @brief A helpful, informational message.\r
  99  *\r
 100  * Log messages with this level may indicate the normal status of a library\r
 101  * function. They should be used to track how far a program has executed.\r
 102  */\r
 103 #define IOT_LOG_INFO     3\r
 104 \r
 105 /**\r
 106  * @brief Detailed and excessive debug information.\r
 107  *\r
 108  * Log messages with this level are intended for developers. They may contain\r
 109  * excessive information such as internal variables, buffers, or other specific\r
 110  * information.\r
 111  */\r
 112 #define IOT_LOG_DEBUG    4\r
 113 \r
 114 /**\r
 115  * @paramstructs{logging,logging}\r
 116  */\r
 117 \r
 118 /**\r
 119  * @ingroup logging_datatypes_paramstructs\r
 120  * @brief Log message configuration struct.\r
 121  *\r
 122  * @paramfor @ref logging_function_log, @ref logging_function_generic\r
 123  *\r
 124  * By default, log messages print the library name, log level, and a timestring.\r
 125  * This struct can be passed to @ref logging_function_generic to disable one of\r
 126  * the above components in the log message.\r
 127  *\r
 128  * <b>Example:</b>\r
 129  *\r
 130  * @code{c}\r
 131  * IotLog_Generic( IOT_LOG_DEBUG, "SAMPLE", IOT_LOG_DEBUG, NULL, "Hello world!" );\r
 132  * @endcode\r
 133  * The code above prints the following message:\r
 134  * @code\r
 135  * [DEBUG][SAMPLE][2018-01-01 12:00:00] Hello world!\r
 136  * @endcode\r
 137  *\r
 138  * The timestring can be disabled as follows:\r
 139  * @code\r
 140  * IotLogConfig_t logConfig = { .hideLogLevel = false, .hideLibraryName = false, .hideTimestring = true};\r
 141  * IotLog_Generic( IOT_LOG_DEBUG, "SAMPLE", IOT_LOG_DEBUG, &logConfig, "Hello world!" );\r
 142  * @endcode\r
 143  * The resulting log message will be:\r
 144  * @code\r
 145  * [DEBUG][SAMPLE] Hello world!\r
 146  * @endcode\r
 147  */\r
 148 typedef struct IotLogConfig\r
 149 {\r
 150     bool hideLogLevel;    /**< @brief Don't print the log level string for this message. */\r
 151     bool hideLibraryName; /**< @brief Don't print the library name for this message. */\r
 152     bool hideTimestring;  /**< @brief Don't print the timestring for this message. */\r
 153 } IotLogConfig_t;\r
 154 \r
 155 /**\r
 156  * @functionspage{logging,logging library}\r
 157  *\r
 158  * - @functionname{logging_function_log}\r
 159  * - @functionname{logging_function_printbuffer}\r
 160  * - @functionname{logging_function_generic}\r
 161  * - @functionname{logging_function_genericprintbuffer}\r
 162  */\r
 163 \r
 164 /**\r
 165  * @functionpage{IotLog_Generic,logging,generic}\r
 166  * @functionpage{IotLog_PrintBuffer,logging,genericprintbuffer}\r
 167  */\r
 168 \r
 169 /**\r
 170  * @brief Generic logging function that prints a single message.\r
 171  *\r
 172  * This function is the generic logging function shared across all libraries.\r
 173  * The library-specific logging function @ref logging_function_log is implemented\r
 174  * using this function. Like @ref logging_function_log, this function is only\r
 175  * available when @ref LIBRARY_LOG_LEVEL is #IOT_LOG_NONE.\r
 176  *\r
 177  * In most cases, the library-specific logging function @ref logging_function_log\r
 178  * should be called instead of this function.\r
 179  *\r
 180  * @param[in] libraryLogSetting The log level setting of the library, used to\r
 181  * determine if the log message should be printed. Must be one of the @ref\r
 182  * logging_constants_levels.\r
 183  * @param[in] pLibraryName The library name to print. See @ref LIBRARY_LOG_NAME.\r
 184  * @param[in] messageLevel The log level of the this message. See @ref LIBRARY_LOG_LEVEL.\r
 185  * @param[in] pLogConfig Pointer to a #IotLogConfig_t. Optional; pass `NULL` to ignore.\r
 186  * @param[in] pFormat Format string for the log message.\r
 187  * @param[in] ... Arguments for format specification.\r
 188  *\r
 189  * @return No return value. On errors, it prints nothing.\r
 190  */\r
 191 /* @[declare_logging_generic] */\r
 192 void IotLog_Generic( int libraryLogSetting,\r
 193                      const char * const pLibraryName,\r
 194                      int messageLevel,\r
 195                      const IotLogConfig_t * const pLogConfig,\r
 196                      const char * const pFormat,\r
 197                      ... );\r
 198 /* @[declare_logging_generic] */\r
 199 \r
 200 /**\r
 201  * @brief Generic function to log the contents of a buffer as bytes.\r
 202  *\r
 203  * This function is the generic buffer logging function shared across all libraries.\r
 204  * The library-specific buffer logging function @ref logging_function_printbuffer is\r
 205  * implemented using this function. Like @ref logging_function_printbuffer, this\r
 206  * function is only available when @ref LIBRARY_LOG_LEVEL is #IOT_LOG_DEBUG.\r
 207  *\r
 208  * In most cases, the library-specific buffer logging function @ref\r
 209  * logging_function_printbuffer should be called instead of this function.\r
 210  *\r
 211  * @param[in] pLibraryName The library name to print with the log. See @ref LIBRARY_LOG_NAME.\r
 212  * @param[in] pHeader A message to print before printing the buffer.\r
 213  * @param[in] pBuffer The buffer to print.\r
 214  * @param[in] bufferSize The number of bytes in `pBuffer` to print.\r
 215  *\r
 216  * @return No return value. On errors, it prints nothing.\r
 217  *\r
 218  * @note To conserve memory, this function only allocates enough memory for a\r
 219  * single line of output. Therefore, in multithreaded systems, its output may\r
 220  * appear "fragmented" if other threads are logging simultaneously.\r
 221  */\r
 222 /* @[declare_logging_genericprintbuffer] */\r
 223 void IotLog_GenericPrintBuffer( const char * const pLibraryName,\r
 224                                 const char * const pHeader,\r
 225                                 const uint8_t * const pBuffer,\r
 226                                 size_t bufferSize );\r
 227 /* @[declare_logging_genericprintbuffer] */\r
 228 \r
 229 #endif /* ifndef IOT_LOGGING_H_ */\r