XnLog.h File Reference

#include "XnOS.h" #include "XnLogTypes.h"
#include "XnDump.h"

Go to the source code of this file.

Defines
#define	XN_MASK_RETVAL_CHECKS   "RetValChecks"
#define	XN_IS_STATUS_OK_LOG_ERROR(what, nRetVal)
Functions
Initialization
Functions for initializing and shutting down the logger.
XN_C_API XnStatus XN_C_DECL	xnLogInitSystem ()
XN_C_API XnStatus XN_C_DECL	xnLogInitFromINIFile (const XnChar *csINIFile, const XnChar *csSectionName)
XN_C_API XnStatus XN_C_DECL	xnLogInitFromXmlFile (const XnChar *strFileName)
XN_C_API XnStatus XN_C_DECL	xnLogClose ()
Filtering Log Messages
Functions for managing filters on the log system.
XN_C_API XnStatus XN_C_DECL	xnLogSetMaskMinSeverity (const XnChar *strMask, XnLogSeverity minSeverity)
XN_C_API XnLogSeverity XN_C_DECL	xnLogGetMaskMinSeverity (const XnChar *strMask)
Log Writers
Functions for managing which writers are active in the log system (i.e. which outputs will be generated).
XN_C_API XnStatus XN_C_DECL	xnLogRegisterLogWriter (XnLogWriter *pWriter)
XN_C_API void XN_C_DECL	xnLogUnregisterLogWriter (XnLogWriter *pWriter)
XN_C_API XnStatus XN_C_DECL	xnLogSetConsoleOutput (XnBool bConsoleOutput)
XN_C_API XnStatus XN_C_DECL	xnLogSetFileOutput (XnBool bFileOutput)
File Output
Functions for configuring how files are created.
XN_C_API XnStatus XN_C_DECL	xnLogStartNewFile ()
XN_C_API XnStatus XN_C_DECL	xnLogSetLineInfo (XnBool bLineInfo)
XN_C_API XnStatus XN_C_DECL	xnLogSetOutputFolder (const XnChar *strOutputFolder)
XN_C_API XnStatus XN_C_DECL	xnLogGetFileName (XnChar *strFileName, XnUInt32 nBufferSize)
Misc.
Miscellaneous functions regarding the log system.
XN_C_API XnStatus XN_C_DECL	xnLogCreateNewFile (const XnChar *strName, XnBool bSessionBased, XnChar *csFullPath, XnUInt32 nPathBufferSize, XN_FILE_HANDLE *phFile)
Variables
XN_C_API XnLogger *	XN_LOGGER_RETVAL_CHECKS
Logger API
Functions for writing entries to the log (used mainly by middleware developers)
#define	xnLoggerClose(pLogger)
#define	xnLoggerWriteHelper(pLogger, severity, csFormat,...)
#define	xnLoggerVerbose(pLogger, csFormat,...)   xnLoggerWriteHelper(pLogger, XN_LOG_VERBOSE, csFormat, __VA_ARGS__)
#define	xnLoggerInfo(pLogger, csFormat,...)   xnLoggerWriteHelper(pLogger, XN_LOG_INFO, csFormat, __VA_ARGS__)
#define	xnLoggerWarning(pLogger, csFormat,...)   xnLoggerWriteHelper(pLogger, XN_LOG_WARNING, csFormat, __VA_ARGS__)
#define	xnLoggerError(pLogger, csFormat,...)   xnLoggerWriteHelper(pLogger, XN_LOG_ERROR, csFormat, __VA_ARGS__)
#define	XN_RETURN_WITH_LOG(pLogger, nRetVal, severity, csFormat,...)
#define	XN_RETURN_WITH_WARNING_LOG(pLogger, nRetVal, csFormat,...)   XN_RETURN_WITH_LOG(pLogger, nRetVal, XN_LOG_WARNING, csFormat, __VA_ARGS__)
#define	XN_RETURN_WITH_ERROR_LOG(pLogger, nRetVal, csFormat,...)   XN_RETURN_WITH_LOG(pLogger, nRetVal, XN_LOG_ERROR, csFormat, __VA_ARGS__)
XN_C_API XnLogger *XN_C_DECL	xnLoggerOpen (const XnChar *strMask)
XN_C_API void XN_C_DECL	xnLoggerWrite (XnLogger *pLogger, XnLogSeverity severity, const XnChar *strFile, XnUInt32 nLine, const XnChar *strFormat,...)
XN_C_API void XN_C_DECL	xnLoggerWriteNoEntry (XnLogger *pLogger, XnLogSeverity severity, const XnChar *strFormat,...)
XN_C_API void XN_C_DECL	xnLoggerWriteBinaryData (XnLogger *pLogger, XnLogSeverity severity, const XnChar *strFile, XnUInt32 nLine, XnUChar *pBinData, XnUInt32 nDataSize, const XnChar *strFormat,...)
XN_C_API XnBool XN_C_DECL	xnLoggerIsEnabled (XnLogger *pLogger, XnLogSeverity severity)

---

Define Documentation

#define XN_IS_STATUS_OK_LOG_ERROR	(		what,
			nRetVal
	)

Value:

if (nRetVal != XN_STATUS_OK)                                                                        \
    {                                                                                                   \
        xnLoggerError(XN_LOGGER_RETVAL_CHECKS, "Failed to " what ": %s", xnGetStatusString(nRetVal));   \
        XN_ASSERT(FALSE);                                                                               \
        return (nRetVal);                                                                               \
    }

Validates return value and writes log message with appropriate status string

#define XN_MASK_RETVAL_CHECKS   "RetValChecks"

#define XN_RETURN_WITH_ERROR_LOG	(		pLogger,
			nRetVal,
			csFormat,
			...
	)		XN_RETURN_WITH_LOG(pLogger, nRetVal, XN_LOG_ERROR, csFormat, __VA_ARGS__)

Helper macro for returning from a function while logging an error

Parameters:

pLogger	[in] The logger to be closed.
nRetVal	[in] The return value from the function.
csFormat	[in] Format string

#define XN_RETURN_WITH_LOG	(		pLogger,
			nRetVal,
			severity,
			csFormat,
			...
	)

Value:

{                                                                                   \
            xnLoggerWriteHelper(pLogger, severity, csFormat, __VA_ARGS__);                  \
            return (nRetVal);                                                               \
        }

Helper macro for returning from a function while logging

Parameters:

pLogger	[in] The logger to be closed.
nRetVal	[in] The return value from the function.
severity	[in] Severity of the log entry
csFormat	[in] Format string

#define XN_RETURN_WITH_WARNING_LOG	(		pLogger,
			nRetVal,
			csFormat,
			...
	)		XN_RETURN_WITH_LOG(pLogger, nRetVal, XN_LOG_WARNING, csFormat, __VA_ARGS__)

Helper macro for returning from a function while logging a warning

Parameters:

pLogger	[in] The logger to be closed.
nRetVal	[in] The return value from the function.
csFormat	[in] Format string

#define xnLoggerClose

(

pLogger

)

Value:

{                                   \
        _xnLoggerClose(pLogger);        \
        pLogger = NULL;                 \
    }

Closes a logger and NULLs the handle.

Parameters:

pLogger

[in] The logger to be closed.

#define xnLoggerError	(		pLogger,
			csFormat,
			...
	)		xnLoggerWriteHelper(pLogger, XN_LOG_ERROR, csFormat, __VA_ARGS__)

Helper macro for logging. Issues an error log entry.

#define xnLoggerInfo	(		pLogger,
			csFormat,
			...
	)		xnLoggerWriteHelper(pLogger, XN_LOG_INFO, csFormat, __VA_ARGS__)

Helper macro for logging. Issues an info log entry.

#define xnLoggerVerbose	(		pLogger,
			csFormat,
			...
	)		xnLoggerWriteHelper(pLogger, XN_LOG_VERBOSE, csFormat, __VA_ARGS__)

Helper macro for logging. Issues a verbose log entry.

#define xnLoggerWarning	(		pLogger,
			csFormat,
			...
	)		xnLoggerWriteHelper(pLogger, XN_LOG_WARNING, csFormat, __VA_ARGS__)

Helper macro for logging. Issues a warning log entry.

#define xnLoggerWriteHelper	(		pLogger,
			severity,
			csFormat,
			...
	)

Value:

if (pLogger != NULL && severity >= pLogger->nMinSeverity)                               \
        {                                                                                       \
            xnLoggerWrite(pLogger, severity, __FILE__, __LINE__, csFormat, __VA_ARGS__);        \
        }

Helper macro for logging. Checks inline if logger is enabled and adds source file and line info.

---

Function Documentation

XN_C_API XnStatus XN_C_DECL xnLogClose

(

)

This function closes the log.

XN_C_API XnStatus XN_C_DECL xnLogCreateNewFile	(	const XnChar *	strName,
		XnBool	bSessionBased,
		XnChar *	csFullPath,
		XnUInt32	nPathBufferSize,
		XN_FILE_HANDLE *	phFile
	)

Creates a new file under the logs directory.

Parameters:

strName	[in] Name of the file to create
bSessionBased	[in] TRUE for a session-based file, FALSE otherwise. A session based file also includes the timestamp and process ID of the running process as a prefix to its name.
csFullPath	[in/out] A buffer to be filled with full path of the created file
nPathBufferSize	[in] The size of the csFullPath buffer
phFile	[out] The file handle

XN_C_API XnBool XN_C_DECL xnLoggerIsEnabled	(	XnLogger *	pLogger,
		XnLogSeverity	severity
	)

Checks if a specific severity is enabled for this logger.

Parameters:

pLogger	[in] Logger to check
severity	[in] Severity to check.

XN_C_API XnLogger* XN_C_DECL xnLoggerOpen

(

const XnChar *

strMask

)

Opens a logger for writing.

Parameters:

strMask

[in] Name of the logger to open.

XN_C_API void XN_C_DECL xnLoggerWrite	(	XnLogger *	pLogger,
		XnLogSeverity	severity,
		const XnChar *	strFile,
		XnUInt32	nLine,
		const XnChar *	strFormat,
			...
	)

Writes a single log entry.

Parameters:

pLogger	[in] Logger to write to
severity	[in] Severity of the log entry
strFile	[in] Name of the source file
nLine	[in] Line in the source file
strFormat	[in] Format string

It is advised to use one of the xnLoggerVerbose, xnLoggerInfo, xnLoggerWarning or xnLoggerError macros instead of calling this method directly.

XN_C_API void XN_C_DECL xnLoggerWriteBinaryData	(	XnLogger *	pLogger,
		XnLogSeverity	severity,
		const XnChar *	strFile,
		XnUInt32	nLine,
		XnUChar *	pBinData,
		XnUInt32	nDataSize,
		const XnChar *	strFormat,
			...
	)

Writes binary data to a logger, formatting it to readable text.

Parameters:

pLogger	[in] Logger to write to
severity	[in] Severity of the log entry
strFile	[in] Name of the source file
nLine	[in] Line in the source file
pBinData	[in] A pointer to the binary data to be written
nDataSize	[in] The number of bytes to write
strFormat	[in] Format string for the binary data header

XN_C_API void XN_C_DECL xnLoggerWriteNoEntry	(	XnLogger *	pLogger,
		XnLogSeverity	severity,
		const XnChar *	strFormat,
			...
	)

Writes to a logger without an entry format (i.e. no timestamp, mask name, etc.)

Parameters:

pLogger	[in] Logger to write to
severity	[in] Severity of the log entry
strFormat	[in] Format string

XN_C_API XnStatus XN_C_DECL xnLogGetFileName	(	XnChar *	strFileName,
		XnUInt32	nBufferSize
	)

Gets current log file name

Parameters:

strFileName	[in] A buffer to be filled
nBufferSize	[in] The size of the buffer

XN_C_API XnLogSeverity XN_C_DECL xnLogGetMaskMinSeverity

(

const XnChar *

strMask

)

Gets the minimum severity to be output from a specific mask (logger name).

Parameters:

strMask

[in] Name of the logger.

Returns:

The minimum severity, or XN_LOG_SEVERITY_NONE is mask will output nothing.

XN_C_API XnStatus XN_C_DECL xnLogInitFromINIFile	(	const XnChar *	csINIFile,
		const XnChar *	csSectionName
	)

This function initializes the log from an INI file.

Parameters:

csINIFile	[in] The name of the INI file.
csSectionName	[in] The name of the section to read values from.

XN_C_API XnStatus XN_C_DECL xnLogInitFromXmlFile

(

const XnChar *

strFileName

)

This function initializes the log from an XML file.

Parameters:

strFileName

[in] The name of the XML file.

XN_C_API XnStatus XN_C_DECL xnLogInitSystem

(

)

This function initializes the log system.

XN_C_API XnStatus XN_C_DECL xnLogRegisterLogWriter

(

XnLogWriter *

pWriter

)

Registers a new Log Writer to receive log entries.

Parameters:

pWriter

[in] The writer to register

XN_C_API XnStatus XN_C_DECL xnLogSetConsoleOutput

(

XnBool

bConsoleOutput

)

Configures if log entries will be printed to console.

Parameters:

bConsoleOutput

[in] TRUE to print log entries to console, FALSE otherwise.

XN_C_API XnStatus XN_C_DECL xnLogSetFileOutput

(

XnBool

bFileOutput

)

Configures if log entries will be printed to a log file.

Parameters:

bFileOutput

[in] TRUE to print log entries to the file, FALSE otherwise.

XN_C_API XnStatus XN_C_DECL xnLogSetLineInfo

(

XnBool

bLineInfo

)

Configures if log entries in file will include the file and line that caused them.

Parameters:

bLineInfo

[in] TRUE to print file and line, FALSE otherwise

XN_C_API XnStatus XN_C_DECL xnLogSetMaskMinSeverity	(	const XnChar *	strMask,
		XnLogSeverity	minSeverity
	)

Sets the minimum severity to be output from a specific mask (logger name).

Parameters:

strMask	[in] Name of the logger.
minSeverity	[in] Minimum severity to be output. Use XN_LOG_SEVERITY_NONE to output nothing.

XN_C_API XnStatus XN_C_DECL xnLogSetOutputFolder

(

const XnChar *

strOutputFolder

)

Configures the folder under which logs will be written.

Parameters:

strOutputFolder

[in] Folder to write to

XN_C_API XnStatus XN_C_DECL xnLogStartNewFile

(

)

This function closes current log file, and starts a new one (if file writer is currently active)

XN_C_API void XN_C_DECL xnLogUnregisterLogWriter

(

XnLogWriter *

pWriter

)

Unregisters a Log Writer from receiving log entries.

Parameters:

pWriter

[in] The writer to unregister

---

Variable Documentation

XN_C_API XnLogger* XN_LOGGER_RETVAL_CHECKS