2 * Amazon FreeRTOS Common V1.0.0
\r
3 * Copyright (C) 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
\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
12 * The above copyright notice and this permission notice shall be included in all
\r
13 * copies or substantial portions of the Software.
\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
22 * http://aws.amazon.com/freertos
\r
23 * http://www.FreeRTOS.org
\r
27 * @file iot_logging.h
\r
28 * @brief Generic logging function header file.
\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
34 * @see iot_logging_setup.h
\r
37 #ifndef IOT_LOGGING_H_
\r
38 #define IOT_LOGGING_H_
\r
40 /* The config header is always included first. */
\r
41 #include "iot_config.h"
\r
43 /* Standard includes. */
\r
44 #include <stdbool.h>
\r
49 * @constantspage{logging,logging library}
\r
51 * @section logging_constants_levels Log levels
\r
52 * @brief Log levels for the libraries in this SDK.
\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
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
72 * @brief No log messages.
\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
78 #define IOT_LOG_NONE 0
\r
81 * @brief Only critical, unrecoverable errors.
\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
86 #define IOT_LOG_ERROR 1
\r
89 * @brief Message about an abnormal but recoverable event.
\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
95 #define IOT_LOG_WARN 2
\r
98 * @brief A helpful, informational message.
\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
103 #define IOT_LOG_INFO 3
\r
106 * @brief Detailed and excessive debug information.
\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
112 #define IOT_LOG_DEBUG 4
\r
115 * @paramstructs{logging,logging}
\r
119 * @ingroup logging_datatypes_paramstructs
\r
120 * @brief Log message configuration struct.
\r
122 * @paramfor @ref logging_function_log, @ref logging_function_generic
\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
131 * IotLog_Generic( IOT_LOG_DEBUG, "SAMPLE", IOT_LOG_DEBUG, NULL, "Hello world!" );
\r
133 * The code above prints the following message:
\r
135 * [DEBUG][SAMPLE][2018-01-01 12:00:00] Hello world!
\r
138 * The timestring can be disabled as follows:
\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
143 * The resulting log message will be:
\r
145 * [DEBUG][SAMPLE] Hello world!
\r
148 typedef struct IotLogConfig
\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
156 * @functionspage{logging,logging library}
\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
165 * @functionpage{IotLog_Generic,logging,generic}
\r
166 * @functionpage{IotLog_PrintBuffer,logging,genericprintbuffer}
\r
170 * @brief Generic logging function that prints a single message.
\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
177 * In most cases, the library-specific logging function @ref logging_function_log
\r
178 * should be called instead of this function.
\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
189 * @return No return value. On errors, it prints nothing.
\r
191 /* @[declare_logging_generic] */
\r
192 void IotLog_Generic( int libraryLogSetting,
\r
193 const char * const pLibraryName,
\r
195 const IotLogConfig_t * const pLogConfig,
\r
196 const char * const pFormat,
\r
198 /* @[declare_logging_generic] */
\r
201 * @brief Generic function to log the contents of a buffer as bytes.
\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
208 * In most cases, the library-specific buffer logging function @ref
\r
209 * logging_function_printbuffer should be called instead of this function.
\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
216 * @return No return value. On errors, it prints nothing.
\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
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
229 #endif /* ifndef IOT_LOGGING_H_ */
\r