AWS IoT Device SDK C: Logging
Generate and print log messages
Return to main page ↑
iot_logging.h File Reference

Generic logging function header file. More...

#include "iot_config.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures

struct  IotLogConfig_t
 Log message configuration struct. More...
 

Macros

#define IOT_LOG_NONE   0
 No log messages. More...
 
#define IOT_LOG_ERROR   1
 Only critical, unrecoverable errors. More...
 
#define IOT_LOG_WARN   2
 Message about an abnormal but recoverable event. More...
 
#define IOT_LOG_INFO   3
 A helpful, informational message. More...
 
#define IOT_LOG_DEBUG   4
 Detailed and excessive debug information. More...
 

Functions

void IotLog_Generic (int32_t libraryLogSetting, const char *const pLibraryName, int32_t messageLevel, const IotLogConfig_t *const pLogConfig, const char *const pFormat,...)
 Generic logging function that prints a single message. More...
 
void IotLog_GenericPrintBuffer (const char *const pLibraryName, const char *const pHeader, const uint8_t *const pBuffer, size_t bufferSize)
 Generic function to log the contents of a buffer as bytes. More...
 

Detailed Description

Generic logging function header file.

Declares the generic logging function and the log levels. This file never needs to be included in source code. The header iot_logging_setup.h should be included instead.

See also
iot_logging_setup.h

Macro Definition Documentation

◆ IOT_LOG_NONE

#define IOT_LOG_NONE   0

No log messages.

Log messages with this level will be silently discarded. When LIBRARY_LOG_LEVEL is IOT_LOG_NONE, logging is disabled and no logging functions can be called.

◆ IOT_LOG_ERROR

#define IOT_LOG_ERROR   1

Only critical, unrecoverable errors.

Log messages with this level will be printed when a library encounters an error from which it cannot easily recover.

◆ IOT_LOG_WARN

#define IOT_LOG_WARN   2

Message about an abnormal but recoverable event.

Log messages with this level will be printed when a library encounters an abnormal event that may be indicative of an error. Libraries should continue execution after logging a warning.

◆ IOT_LOG_INFO

#define IOT_LOG_INFO   3

A helpful, informational message.

Log messages with this level may indicate the normal status of a library function. They should be used to track how far a program has executed.

◆ IOT_LOG_DEBUG

#define IOT_LOG_DEBUG   4

Detailed and excessive debug information.

Log messages with this level are intended for developers. They may contain excessive information such as internal variables, buffers, or other specific information.

Function Documentation

◆ IotLog_Generic()

void IotLog_Generic ( int32_t  libraryLogSetting,
const char *const  pLibraryName,
int32_t  messageLevel,
const IotLogConfig_t *const  pLogConfig,
const char *const  pFormat,
  ... 
)

Generic logging function that prints a single message.

This function is the generic logging function shared across all libraries. The library-specific logging function IotLog is implemented using this function. Like IotLog, this function is only available when LIBRARY_LOG_LEVEL is IOT_LOG_NONE.

In most cases, the library-specific logging function IotLog should be called instead of this function.

Parameters
[in]libraryLogSettingThe log level setting of the library, used to determine if the log message should be printed. Must be one of the Log levels.
[in]pLibraryNameThe library name to print. See LIBRARY_LOG_NAME.
[in]messageLevelThe log level of the this message. See LIBRARY_LOG_LEVEL.
[in]pLogConfigPointer to a IotLogConfig_t. Optional; pass NULL to ignore.
[in]pFormatFormat string for the log message.
[in]...Arguments for format specification.
Returns
No return value. On errors, it prints nothing.

◆ IotLog_GenericPrintBuffer()

void IotLog_GenericPrintBuffer ( const char *const  pLibraryName,
const char *const  pHeader,
const uint8_t *const  pBuffer,
size_t  bufferSize 
)

Generic function to log the contents of a buffer as bytes.

This function is the generic buffer logging function shared across all libraries. The library-specific buffer logging function IotLog_PrintBuffer is implemented using this function. Like IotLog_PrintBuffer, this function is only available when LIBRARY_LOG_LEVEL is IOT_LOG_DEBUG.

In most cases, the library-specific buffer logging function IotLog_PrintBuffer should be called instead of this function.

Parameters
[in]pLibraryNameThe library name to print with the log. See LIBRARY_LOG_NAME.
[in]pHeaderA message to print before printing the buffer.
[in]pBufferThe buffer to print.
[in]bufferSizeThe number of bytes in pBuffer to print.
Returns
No return value. On errors, it prints nothing.
Note
To conserve memory, this function only allocates enough memory for a single line of output. Therefore, in multithreaded systems, its output may appear "fragmented" if other threads are logging simultaneously.