--- /dev/null
+/*\r
+ * IoT Common V1.1.0\r
+ * Copyright (C) 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.\r
+ *\r
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
+ * this software and associated documentation files (the "Software"), to deal in\r
+ * the Software without restriction, including without limitation the rights to\r
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
+ * the Software, and to permit persons to whom the Software is furnished to do so,\r
+ * subject to the following conditions:\r
+ *\r
+ * The above copyright notice and this permission notice shall be included in all\r
+ * copies or substantial portions of the Software.\r
+ *\r
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
+ */\r
+\r
+/**\r
+ * @file iot_logging_setup.h\r
+ * @brief Defines the logging macro #IotLog.\r
+ */\r
+\r
+#ifndef IOT_LOGGING_SETUP_H_\r
+#define IOT_LOGGING_SETUP_H_\r
+\r
+/* The config header is always included first. */\r
+#include "iot_config.h"\r
+\r
+/* Logging include. Because it's included here, iot_logging.h never needs\r
+ * to be included in source. */\r
+#include "iot_logging.h"\r
+\r
+/**\r
+ * @functionpage{IotLog,logging,log}\r
+ * @functionpage{IotLog_PrintBuffer,logging,printbuffer}\r
+ */\r
+\r
+/**\r
+ * @def IotLog( messageLevel, pLogConfig, ... )\r
+ * @brief Logging function for a specific library. In most cases, this is the\r
+ * logging function to call.\r
+ *\r
+ * This function prints a single log message. It is available when @ref\r
+ * LIBRARY_LOG_LEVEL is not #IOT_LOG_NONE. Log messages automatically\r
+ * include the [log level](@ref logging_constants_levels), [library name]\r
+ * (@ref LIBRARY_LOG_NAME), and time. An optional @ref IotLogConfig_t may\r
+ * be passed to this function to hide information for a single log message.\r
+ *\r
+ * The logging library must be set up before this function may be called. See\r
+ * @ref logging_setup_use for more information.\r
+ *\r
+ * This logging function also has the following abbreviated forms that can be used\r
+ * when an #IotLogConfig_t isn't needed.\r
+ *\r
+ * Name | Equivalent to\r
+ * ---- | -------------\r
+ * #IotLogError | @code{c} IotLog( IOT_LOG_ERROR, NULL, ... ) @endcode\r
+ * #IotLogWarn | @code{c} IotLog( IOT_LOG_WARN, NULL, ... ) @endcode\r
+ * #IotLogInfo | @code{c} IotLog( IOT_LOG_INFO, NULL, ... ) @endcode\r
+ * #IotLogDebug | @code{c} IotLog( IOT_LOG_DEBUG, NULL, ... ) @endcode\r
+ *\r
+ * @param[in] messageLevel Log level of this message. Must be one of the\r
+ * @ref logging_constants_levels.\r
+ * @param[in] pLogConfig Pointer to an #IotLogConfig_t. Optional; pass `NULL`\r
+ * to ignore.\r
+ * @param[in] ... Message and format specification.\r
+ *\r
+ * @return No return value. On errors, it prints nothing.\r
+ *\r
+ * @note This function may be implemented as a macro.\r
+ * @see @ref logging_function_generic for the generic (not library-specific)\r
+ * logging function.\r
+ */\r
+\r
+/**\r
+ * @def IotLog_PrintBuffer( pHeader, pBuffer, bufferSize )\r
+ * @brief Log the contents of buffer as bytes. Only available when @ref\r
+ * LIBRARY_LOG_LEVEL is #IOT_LOG_DEBUG.\r
+ *\r
+ * This function prints the bytes located at a given memory address. It is\r
+ * intended for debugging only, and is therefore only available when @ref\r
+ * LIBRARY_LOG_LEVEL is #IOT_LOG_DEBUG.\r
+ *\r
+ * Log messages printed by this function <b>always</b> include the [log level]\r
+ * (@ref logging_constants_levels), [library name](@ref LIBRARY_LOG_NAME),\r
+ * and time. In addition, this function may print an optional header `pHeader`\r
+ * before it prints the contents of the buffer. This function does not have an\r
+ * #IotLogConfig_t parameter.\r
+ *\r
+ * The logging library must be set up before this function may be called. See\r
+ * @ref logging_setup_use for more information.\r
+ *\r
+ * @param[in] pHeader A message to log before the buffer. Optional; pass `NULL`\r
+ * to ignore.\r
+ * @param[in] pBuffer Pointer to start of buffer.\r
+ * @param[in] bufferSize Size of `pBuffer`.\r
+ *\r
+ * @return No return value. On errors, it prints nothing.\r
+ *\r
+ * @note This function may be implemented as a macro.\r
+ * @note To conserve memory, @ref logging_function_genericprintbuffer (the underlying\r
+ * implementation) only allocates enough memory for a single line of output. Therefore,\r
+ * in multithreaded systems, its output may appear "fragmented" if other threads are\r
+ * logging simultaneously.\r
+ * @see @ref logging_function_genericprintbuffer for the generic (not library-specific)\r
+ * buffer logging function.\r
+ *\r
+ * <b>Example</b>\r
+ * @code{c}\r
+ * const uint8_t pBuffer[] = { 0x00, 0x01, 0x02, 0x03 };\r
+ *\r
+ * IotLog_PrintBuffer( "This buffer contains:",\r
+ * pBuffer,\r
+ * 4 );\r
+ * @endcode\r
+ * The code above prints something like the following:\r
+ * @code{c}\r
+ * [DEBUG][LIB_NAME][2018-01-01 12:00:00] This buffer contains:\r
+ * 00 01 02 03\r
+ * @endcode\r
+ */\r
+\r
+/**\r
+ * @def IotLogError( ... )\r
+ * @brief Abbreviated logging macro for level #IOT_LOG_ERROR.\r
+ *\r
+ * Equivalent to:\r
+ * @code{c}\r
+ * IotLog( IOT_LOG_ERROR, NULL, ... )\r
+ * @endcode\r
+ */\r
+\r
+/**\r
+ * @def IotLogWarn( ... )\r
+ * @brief Abbreviated logging macro for level #IOT_LOG_WARN.\r
+ *\r
+ * Equivalent to:\r
+ * @code{c}\r
+ * IotLog( IOT_LOG_WARN, NULL, ... )\r
+ * @endcode\r
+ */\r
+\r
+/**\r
+ * @def IotLogInfo( ... )\r
+ * @brief Abbreviated logging macro for level #IOT_LOG_INFO.\r
+ *\r
+ * Equivalent to:\r
+ * @code{c}\r
+ * IotLog( IOT_LOG_INFO, NULL, ... )\r
+ * @endcode\r
+ */\r
+\r
+/**\r
+ * @def IotLogDebug( ... )\r
+ * @brief Abbreviated logging macro for level #IOT_LOG_DEBUG.\r
+ *\r
+ * Equivalent to:\r
+ * @code{c}\r
+ * IotLog( IOT_LOG_DEBUG, NULL, ... )\r
+ * @endcode\r
+ */\r
+\r
+/* Check that LIBRARY_LOG_LEVEL is defined and has a valid value. */\r
+#if !defined( LIBRARY_LOG_LEVEL ) || \\r
+ ( LIBRARY_LOG_LEVEL != IOT_LOG_NONE && \\r
+ LIBRARY_LOG_LEVEL != IOT_LOG_ERROR && \\r
+ LIBRARY_LOG_LEVEL != IOT_LOG_WARN && \\r
+ LIBRARY_LOG_LEVEL != IOT_LOG_INFO && \\r
+ LIBRARY_LOG_LEVEL != IOT_LOG_DEBUG )\r
+ #error "Please define LIBRARY_LOG_LEVEL as either IOT_LOG_NONE, IOT_LOG_ERROR, IOT_LOG_WARN, IOT_LOG_INFO, or IOT_LOG_DEBUG."\r
+/* Check that LIBRARY_LOG_NAME is defined and has a valid value. */\r
+#elif !defined( LIBRARY_LOG_NAME )\r
+ #error "Please define LIBRARY_LOG_NAME."\r
+#else\r
+ /* Define IotLog if the log level is greater than "none". */\r
+ #if LIBRARY_LOG_LEVEL > IOT_LOG_NONE\r
+ #define IotLog( messageLevel, pLogConfig, ... ) \\r
+ IotLog_Generic( LIBRARY_LOG_LEVEL, \\r
+ LIBRARY_LOG_NAME, \\r
+ messageLevel, \\r
+ pLogConfig, \\r
+ __VA_ARGS__ )\r
+\r
+ /* Define the abbreviated logging macros. */\r
+ #define IotLogError( ... ) IotLog( IOT_LOG_ERROR, NULL, __VA_ARGS__ )\r
+ #define IotLogWarn( ... ) IotLog( IOT_LOG_WARN, NULL, __VA_ARGS__ )\r
+ #define IotLogInfo( ... ) IotLog( IOT_LOG_INFO, NULL, __VA_ARGS__ )\r
+ #define IotLogDebug( ... ) IotLog( IOT_LOG_DEBUG, NULL, __VA_ARGS__ )\r
+\r
+ /* If log level is DEBUG, enable the function to print buffers. */\r
+ #if LIBRARY_LOG_LEVEL >= IOT_LOG_DEBUG\r
+ #define IotLog_PrintBuffer( pHeader, pBuffer, bufferSize ) \\r
+ IotLog_GenericPrintBuffer( LIBRARY_LOG_NAME, \\r
+ pHeader, \\r
+ pBuffer, \\r
+ bufferSize )\r
+ #else\r
+ #define IotLog_PrintBuffer( pHeader, pBuffer, bufferSize )\r
+ #endif\r
+ /* Remove references to IotLog from the source code if logging is disabled. */\r
+ #else\r
+ /* @[declare_logging_log] */\r
+ #define IotLog( messageLevel, pLogConfig, ... )\r
+ /* @[declare_logging_log] */\r
+ /* @[declare_logging_printbuffer] */\r
+ #define IotLog_PrintBuffer( pHeader, pBuffer, bufferSize )\r
+ /* @[declare_logging_printbuffer] */\r
+ #define IotLogError( ... )\r
+ #define IotLogWarn( ... )\r
+ #define IotLogInfo( ... )\r
+ #define IotLogDebug( ... )\r
+ #endif\r
+#endif\r
+\r
+#endif /* ifndef IOT_LOGGING_SETUP_H_ */\r
projects / freertos / blobdiff