cdi_logger_api.h File Reference

The declarations in this header file correspond to the definitions in logger.c. More...

#include <stdbool.h>
#include "cdi_utility_api.h"
#include "cdi_log_api.h"
#include "cdi_os_api.h"

Go to the source code of this file.

Data Structures
struct	CdiLogMultilineState
	Structure used to hold state data for a multiline log message. More...

Macros
#define	CDI_MAX_LOG_STRING_LENGTH   (1024)
	Maximum length of log message string used in logger.c.
#define	CDI_MAX_LOG_FUNCTION_NAME_STRING_LENGTH   (128)
	Maximum length of log message function name string used in logger.c.
#define	CDI_LOG_THREAD(log_level, ...)    CdiLogger(CdiLoggerThreadLogGet(), kLogComponentGeneric, log_level, __FUNCTION__, __LINE__, __VA_ARGS__)
	Macro used to generate a formatted log line and send the message to the log associated with the calling thread using CdiLoggerThreadLogSet(). If no log is associated with the calling thread, then stdout is used. To set the log level use CdiLoggerLevelSet() with kLogComponentGeneric for the component parameter.
#define	CDI_LOG_THREAD_COMPONENT(log_level, component, ...)    CdiLogger(CdiLoggerThreadLogGet(), component, log_level, __FUNCTION__, __LINE__, __VA_ARGS__)
	Macro used to generate a formatted log line for the specified log component and send the message to the log associated with the calling thread using CdiLoggerThreadLogSet(). If no log is associated with the calling thread, then stdout is used. To enable/disable logging of the specified component, use CdiLoggerComponentEnable(). To set the log level use CdiLoggerLevelSet().
#define	CDI_LOG_HANDLE(log_handle, log_level, ...)    CdiLogger(log_handle, kLogComponentGeneric, log_level, __FUNCTION__, __LINE__, __VA_ARGS__)
	Macro used to generate a formatted log line and send to the specified log.
#define	CDI_LOG_THREAD_MULTILINE_BEGIN(log_level, multiline_state_ptr)
	Macro used to start the generation of a multiple line log message. Use this once, followed by any number of CDI_LOG_MULTILINE() macros to generate each log line. End the multiple line log message using CDI_LOG_MULTILINE_END(). The log messages are sent to the log associated with the calling thread using CdiLoggerThreadLogSet(). If no log is associated with the calling thread, then stdout is used.
#define	CDI_LOG_MULTILINE(multiline_state_ptr, ...)    CdiLoggerMultiline(multiline_state_ptr, __VA_ARGS__)
	Macro used to send a single line of a multiple line log message. Must use CDI_LOG_MULTILINE_BEGIN() once before using this macro and CDI_LOG_MULTILINE_END() once after all the lines have been generated.
#define	CDI_LOG_MULTILINE_END(multiline_handle)   CdiLoggerMultilineEnd(multiline_handle)
	Macro used to end a multiple line log message and send to the log. CDI_LOG_MULTILINE_BEGIN() must be used once to start the multiline log message and define which log to send the message to. Each log line must be generated using CDI_LOG_MULTILINE().
#define	CDI_LOG_WHEN(log_level, condition, number, ...)
	Macro that generates log output conditionally to the global log handle. This macro works by evaluating a condition that the user provides, and assuming the condition is 'true', will filter messages to every 'number' of occurrences. If no conditional logic is needed to filter logging, provide a value of 'true' as the 'condition' parameter.
#define	CDI_LOG_THREAD_WHEN(log_level, condition, number, ...)
	Macro that generates log output conditionally to a thread handle. This macro works by evaluating a condition that the user provides, and assuming the condition is 'true', will filter messages to every 'number' of occurrences. If no conditional logic is needed to filter logging, provide a value of 'true' as the 'condition' parameter.

Typedefs
typedef struct CdiLoggerState *	CdiLoggerHandle
	Type used as the handle (pointer to an opaque structure) for a logger instance. Each handle represents an instance of a logger. A logger is used to hold multiple logs and a single global log.
typedef struct CdiLogState *	CdiLogHandle
	Type used as the handle (pointer to an opaque structure) for a log. Each handle represents an instance of a log.
typedef struct CdiMultilineLogBufferState	CdiMultilineLogBufferState
	Structure used to hold a buffer for a multiline log message.

Functions
CDI_INTERFACE bool	CdiLoggerInitialize (void)
CDI_INTERFACE bool	CdiLoggerCreate (CdiLogLevel default_log_level, CdiLoggerHandle *ret_logger_handle_ptr)
CDI_INTERFACE bool	CdiLoggerCreateLog (CdiLoggerHandle logger_handle, CdiConnectionHandle con_handle, const CdiLogMethodData *log_method_data_ptr, CdiLogHandle *ret_log_handle_ptr)
CDI_INTERFACE bool	CdiLoggerCreateFileLog (CdiLoggerHandle logger_handle, const char *filename_str, CdiLogHandle *ret_log_handle_ptr)
CDI_INTERFACE void	CdiLogger (CdiLogHandle handle, CdiLogComponent component, CdiLogLevel log_level, const char *function_name_str, int line_number, const char *format_str,...)
CDI_INTERFACE void	CdiLoggerLogFromCallback (CdiLogHandle handle, const CdiLogMessageCbData *cb_data_ptr)
CDI_INTERFACE bool	CdiLoggerThreadLogSet (CdiLogHandle handle)
CDI_INTERFACE void	CdiLoggerThreadLogUnset (void)
CDI_INTERFACE CdiLogHandle	CdiLoggerThreadLogGet (void)
CDI_INTERFACE void	CdiLoggerMultilineBegin (CdiLogHandle handle, CdiLogComponent component, CdiLogLevel log_level, const char *function_name_str, int line_number, CdiLogMultilineState *state_ptr)
CDI_INTERFACE void	CdiLoggerMultiline (CdiLogMultilineState *state_ptr, const char *format_str,...)
CDI_INTERFACE char *	CdiLoggerMultilineGetBuffer (CdiLogMultilineState *state_ptr)
CDI_INTERFACE void	CdiLoggerMultilineEnd (CdiLogMultilineState *state_ptr)
CDI_INTERFACE void	CdiLoggerFlushAllFileLogs (void)
CDI_INTERFACE bool	CdiLoggerIsEnabled (CdiLogHandle handle, CdiLogComponent component, CdiLogLevel log_level)
CDI_INTERFACE CdiReturnStatus	CdiLoggerComponentEnable (CdiLogHandle handle, CdiLogComponent component, bool enable)
CDI_INTERFACE CdiReturnStatus	CdiLoggerComponentEnableGlobal (CdiLogComponent component, bool enable)
CDI_INTERFACE bool	CdiLoggerComponentIsEnabled (CdiLogHandle handle, CdiLogComponent component)
CDI_INTERFACE CdiReturnStatus	CdiLoggerLevelSet (CdiLogHandle handle, CdiLogComponent component, CdiLogLevel level)
CDI_INTERFACE CdiReturnStatus	CdiLoggerLevelSetGlobal (CdiLogComponent component, CdiLogLevel level)
CDI_INTERFACE CdiReturnStatus	CdiLoggerStderrEnable (bool enable, CdiLogLevel level)
CDI_INTERFACE void	CdiLoggerDestroyLog (CdiLogHandle handle)
CDI_INTERFACE void	CdiLoggerDestroyLogger (CdiLoggerHandle logger_handle)
CDI_INTERFACE void	CdiLoggerShutdown (bool force)

Detailed Description

The declarations in this header file correspond to the definitions in logger.c.

Macro Definition Documentation

CDI_LOG_HANDLE

#define CDI_LOG_HANDLE	(		log_handle,
			log_level,
			... )    CdiLogger(log_handle, kLogComponentGeneric, log_level, __FUNCTION__, __LINE__, __VA_ARGS__)

Macro used to generate a formatted log line and send to the specified log.

Parameters

log_handle	Handle of log to send log message to.
log_level	The log level for this message. The remaining parameters contain a variable length list of arguments. The first argument must be the format string.

CDI_LOG_THREAD

#define CDI_LOG_THREAD	(		log_level,
			... )    CdiLogger(CdiLoggerThreadLogGet(), kLogComponentGeneric, log_level, __FUNCTION__, __LINE__, __VA_ARGS__)

Macro used to generate a formatted log line and send the message to the log associated with the calling thread using CdiLoggerThreadLogSet(). If no log is associated with the calling thread, then stdout is used. To set the log level use CdiLoggerLevelSet() with kLogComponentGeneric for the component parameter.

Parameters

log_level

The log level for this message. The remaining parameters contain a variable length list of arguments. The first argument must be the format string.

CDI_LOG_THREAD_COMPONENT

#define CDI_LOG_THREAD_COMPONENT	(		log_level,
			component,
			... )    CdiLogger(CdiLoggerThreadLogGet(), component, log_level, __FUNCTION__, __LINE__, __VA_ARGS__)

Macro used to generate a formatted log line for the specified log component and send the message to the log associated with the calling thread using CdiLoggerThreadLogSet(). If no log is associated with the calling thread, then stdout is used. To enable/disable logging of the specified component, use CdiLoggerComponentEnable(). To set the log level use CdiLoggerLevelSet().

Parameters

log_level	The log level for this message.
component	Specifies which component to monitor. (E.g. kLogComponentProbe) The remaining parameters contain a variable length list of arguments. The first argument must be the format string.

CDI_LOG_THREAD_MULTILINE_BEGIN

#define CDI_LOG_THREAD_MULTILINE_BEGIN	(		log_level,
			multiline_state_ptr )

Value:

    CdiLoggerMultilineBegin(CdiLoggerThreadLogGet(), kLogComponentGeneric, log_level, __FUNCTION__, __LINE__, \
    multiline_state_ptr)

Macro used to start the generation of a multiple line log message. Use this once, followed by any number of CDI_LOG_MULTILINE() macros to generate each log line. End the multiple line log message using CDI_LOG_MULTILINE_END(). The log messages are sent to the log associated with the calling thread using CdiLoggerThreadLogSet(). If no log is associated with the calling thread, then stdout is used.

CDI_LOG_THREAD_WHEN

#define CDI_LOG_THREAD_WHEN	(		log_level,
			condition,
			number,
			... )

Value:

    do { \
        static uint64_t log_event_count = 0; \
        if (condition) { \
            CdiOsAtomicInc64(&log_event_count); \
            if ((number) > 0 && (1 == log_event_count % (number) || 1 == (number))) { \
                if (1 < (number)) { \
                    CDI_LOG_HANDLE(CdiLoggerThreadLogGet(), kLogInfo, "The following message has " \
                                   "occurred [%llu] times.", log_event_count); \
                } \
                CdiLogger(CdiLoggerThreadLogGet(), kLogComponentGeneric, log_level, \
                          __FUNCTION__, __LINE__, ##__VA_ARGS__); \
            } \
        } \
    } while (0)

Macro that generates log output conditionally to a thread handle. This macro works by evaluating a condition that the user provides, and assuming the condition is 'true', will filter messages to every 'number' of occurrences. If no conditional logic is needed to filter logging, provide a value of 'true' as the 'condition' parameter.

CDI_LOG_WHEN

#define CDI_LOG_WHEN	(		log_level,
			condition,
			number,
			... )

Value:

    do { \
        static uint64_t log_event_count = 0; \
        if (condition) { \
            CdiOsAtomicInc64(&log_event_count); \
            if ((number) > 0 && (1 == log_event_count % (number) || 1 == (number))) { \
                if (1 < (number)) { \
                    CDI_LOG_HANDLE(CdiLogGlobalGet(), kLogInfo, "The following message has " \
                                   "occurred [%llu] times.", log_event_count); \
                } \
                CdiLogger(CdiLogGlobalGet(), kLogComponentGeneric, log_level, __FUNCTION__, __LINE__, ##__VA_ARGS__); \
            } \
        } \
    } while (0)

Macro that generates log output conditionally to the global log handle. This macro works by evaluating a condition that the user provides, and assuming the condition is 'true', will filter messages to every 'number' of occurrences. If no conditional logic is needed to filter logging, provide a value of 'true' as the 'condition' parameter.

Function Documentation

CdiLogger()

CDI_INTERFACE void CdiLogger	(	CdiLogHandle	handle,
		CdiLogComponent	component,
		CdiLogLevel	log_level,
		const char *	function_name_str,
		int	line_number,
		const char *	format_str,
			... )

Function used to generate a formatted log line.

Parameters

handle	Log handle.
component	Component that is generating this message.
log_level	Level of logging for this message.
function_name_str	Pointer to name of function the log line is being generated from. If NULL, function name and source code line number are not used.
line_number	Source code line number the log message is being generated from.
format_str	Pointer to string used for formatting the message. The remaining parameters contain a variable length list of arguments used by the format string to generate the log message.

CdiLoggerComponentEnable()

CDI_INTERFACE CdiReturnStatus CdiLoggerComponentEnable	(	CdiLogHandle	handle,
		CdiLogComponent	component,
		bool	enable )

See also

CdiLogComponentEnable

CdiLoggerComponentEnableGlobal()

CDI_INTERFACE CdiReturnStatus CdiLoggerComponentEnableGlobal	(	CdiLogComponent	component,
		bool	enable )

See also

CdiLogComponentEnableGlobal

CdiLoggerComponentIsEnabled()

CDI_INTERFACE bool CdiLoggerComponentIsEnabled	(	CdiLogHandle	handle,
		CdiLogComponent	component )

See also

CdiLogComponentIsEnabled

CdiLoggerCreate()

CDI_INTERFACE bool CdiLoggerCreate	(	CdiLogLevel	default_log_level,
		CdiLoggerHandle *	ret_logger_handle_ptr )

Create an instance of the logger.

Parameters

default_log_level	The default log level to use.
ret_logger_handle_ptr	Pointer to returned handle of the new logger.

Returns

true successfully initialized; false if not.

CdiLoggerCreateFileLog()

CDI_INTERFACE bool CdiLoggerCreateFileLog	(	CdiLoggerHandle	logger_handle,
		const char *	filename_str,
		CdiLogHandle *	ret_log_handle_ptr )

Create a file log.

Parameters

logger_handle	Handle of logger to create file log in.
filename_str	String representing the log file to create. If NULL, then output will be directed to stdout.
ret_log_handle_ptr	Pointer to returned handle of the new log.

Returns

true successfully initialized; false if not.

CdiLoggerCreateLog()

CDI_INTERFACE bool CdiLoggerCreateLog	(	CdiLoggerHandle	logger_handle,
		CdiConnectionHandle	con_handle,
		const CdiLogMethodData *	log_method_data_ptr,
		CdiLogHandle *	ret_log_handle_ptr )

Create a log using the specified log configuration data.

Parameters

logger_handle	Handle of logger to create log in.
con_handle	Handle of connection to associate with this log. If NULL, the global log is assumed.
log_method_data_ptr	Pointer to log method configuration data.
ret_log_handle_ptr	Pointer to returned handle of the new log.

Returns

true if successful, false if not.

CdiLoggerDestroyLog()

CDI_INTERFACE void CdiLoggerDestroyLog

(

CdiLogHandle

handle

)

Closes a log file and destroys the resources used by the instance of the specified log.

Parameters

handle

Log handle.

CdiLoggerDestroyLogger()

CDI_INTERFACE void CdiLoggerDestroyLogger

(

CdiLoggerHandle

logger_handle

)

Destroys the resources used by the instance of the specified logger.

Parameters

logger_handle

Logger handle.

CdiLoggerFlushAllFileLogs()

CDI_INTERFACE void CdiLoggerFlushAllFileLogs

(

void

)

Flush all file logs.

CdiLoggerInitialize()

CDI_INTERFACE bool CdiLoggerInitialize

(

void

)

Initialize the logger. Must be called once before using any other functions in the logger.

CdiLoggerIsEnabled()

CDI_INTERFACE bool CdiLoggerIsEnabled	(	CdiLogHandle	handle,
		CdiLogComponent	component,
		CdiLogLevel	log_level )

Determine if a specific log component and level is enabled for logging.

Parameters

handle	Log handle.
component	Component to check.
log_level	Level to check.

Returns

True if enabled, otherwise false.

CdiLoggerLevelSet()

CDI_INTERFACE CdiReturnStatus CdiLoggerLevelSet	(	CdiLogHandle	handle,
		CdiLogComponent	component,
		CdiLogLevel	level )

See also

CdiLogLevelSet

CdiLoggerLevelSetGlobal()

CDI_INTERFACE CdiReturnStatus CdiLoggerLevelSetGlobal	(	CdiLogComponent	component,
		CdiLogLevel	level )

See also

CdiLogLevelSetGlobal

CdiLoggerLogFromCallback()

CDI_INTERFACE void CdiLoggerLogFromCallback	(	CdiLogHandle	handle,
		const CdiLogMessageCbData *	cb_data_ptr )

Generate a formatted log line from logger callback data.

Parameters

handle	Log handle to write the message to. Must be using a kLogMethodStdout or kLogMethodFile log method.
cb_data_ptr	Logger callback data used to generate the log message.

CdiLoggerMultiline()

CDI_INTERFACE void CdiLoggerMultiline	(	CdiLogMultilineState *	state_ptr,
		const char *	format_str,
			... )

Add a line to a multiline log message buffer.

Parameters

state_ptr	Pointer to multiline state data created using CdiLoggerMultilineBegin().
format_str	Pointer to string used for formatting the message. The remaining parameters contain a variable length list of arguments used by the format string to generate the console message.

CdiLoggerMultilineBegin()

CDI_INTERFACE void CdiLoggerMultilineBegin	(	CdiLogHandle	handle,
		CdiLogComponent	component,
		CdiLogLevel	log_level,
		const char *	function_name_str,
		int	line_number,
		CdiLogMultilineState *	state_ptr )

Begin a multiline log message, creating a buffer to hold the log message lines.

Parameters

handle	Log handle.
component	Component that is generating this message.
log_level	Level of logging for this message.
function_name_str	Pointer to name of function the log line is being generated from. If NULL, function name and source code line number are not used.
line_number	Source code line number the log message is being generated from.
state_ptr	Pointer to address where to write returned multiline state data.

CdiLoggerMultilineEnd()

CDI_INTERFACE void CdiLoggerMultilineEnd

(

CdiLogMultilineState *

state_ptr

)

End the multiline lo message and write to the log as a single message. Resources used by the multiline log will be released.

Parameters

state_ptr

Pointer to multiline state data created using CdiLoggerMultilineBegin().

CdiLoggerMultilineGetBuffer()

CDI_INTERFACE char * CdiLoggerMultilineGetBuffer

(

CdiLogMultilineState *

state_ptr

)

Return pointer to multiline log buffer. Marks the buffer as used, so CdiLoggerMultilineEnd() won't generate any output.

Parameters

state_ptr

Pointer to multiline state data created using CdiLoggerMultilineBegin().

Returns

Pointer to log buffer or NULL when logger is disabled.

CdiLoggerShutdown()

CDI_INTERFACE void CdiLoggerShutdown

(

bool

force

)

Shutdown the logger. Must be called once for each time CdiLoggerInitialize() has been called. An internal reference counter is maintained. When it reaches zero or the provided "force" parameter is true, the resources are freed.

Parameters

force

Use true to forcibly shutdown the logger closing any open files. Should only be used in abnormal shutdown conditions, otherwise should always be false.

CdiLoggerStderrEnable()

CDI_INTERFACE CdiReturnStatus CdiLoggerStderrEnable	(	bool	enable,
		CdiLogLevel	level )

See also

CdiLogStderrEnable

CdiLoggerThreadLogGet()

CDI_INTERFACE CdiLogHandle CdiLoggerThreadLogGet

(

void

)

Get log handle associated with the calling thread.

Returns

Log handle associated with calling thread or NULL when the logger has not been initialized.

CdiLoggerThreadLogSet()

CDI_INTERFACE bool CdiLoggerThreadLogSet

(

CdiLogHandle

handle

)

Associate the specified log with the calling thread. Subsequent calls to non-global CdiLog functions by this thread will write to the specified log.

Parameters

handle

Log handle.

Returns

true successfully initialized; false if not.

CdiLoggerThreadLogUnset()

CDI_INTERFACE void CdiLoggerThreadLogUnset

(

void

)

Remove any association of the calling thread with a logger. Subsequent calls to non-global CdiLog functions by this thread will write to the global logger (if one exists) or to stdout.