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]	libraryLogSetting	The log level setting of the library, used to determine if the log message should be printed. Must be one of the Log levels.
[in]	pLibraryName	The library name to print. See LIBRARY_LOG_NAME.
[in]	messageLevel	The log level of the this message. See LIBRARY_LOG_LEVEL.
[in]	pLogConfig	Pointer to a IotLogConfig_t. Optional; pass NULL to ignore.
[in]	pFormat	Format 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]	pLibraryName	The library name to print with the log. See LIBRARY_LOG_NAME.
[in]	pHeader	A message to print before printing the buffer.
[in]	pBuffer	The buffer to print.
[in]	bufferSize	The 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.