XnLog.h File Reference
`#include "XnOS.h"`
`#include "XnLogTypes.h"`
`#include "XnDump.h"`

Go to the source code of this file.

## 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)

## 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, ...)
#define | xnLoggerInfo(pLogger, csFormat, ...)
#define | xnLoggerWarning(pLogger, csFormat, ...)
#define | xnLoggerError(pLogger, csFormat, ...)
#define | XN_RETURN_WITH_LOG(pLogger, nRetVal, severity, csFormat, ...)
#define | XN_RETURN_WITH_WARNING_LOG(pLogger, nRetVal, csFormat, ...)
#define | XN_RETURN_WITH_ERROR_LOG(pLogger, nRetVal, csFormat, ...)
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)

## Misc.

Miscellaneous functions regarding the log system.
#define | XN_MASK_RETVAL_CHECKS "RetValChecks"
#define | XN_IS_STATUS_OK_LOG_ERROR(what, nRetVal)
XnLogger * | XN_LOGGER_RETVAL_CHECKS
XN_C_API XnStatus XN_C_DECL | xnLogCreateNewFile (const XnChar *strName, XnBool bSessionBased, XnChar *csFullPath, XnUInt32 nPathBufferSize, XN_FILE_HANDLE *phFile)

## Macro Definition Documentation

## XN_IS_STATUS_OK_LOG_ERROR

#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); \
}
XN_LOGGER_RETVAL_CHECKS
XnLogger * XN_LOGGER_RETVAL_CHECKS
Definition XnLog.h:413
FALSE
#define FALSE
Definition XnPlatform.h:100
XN_STATUS_OK
#define XN_STATUS_OK
Definition XnStatus.h:37
xnGetStatusString
XN_C_API const XnChar *XN_C_DECL xnGetStatusString(const XnStatus Status)

Validates return value and writes log message with appropriate status string

## XN_MASK_RETVAL_CHECKS

#define XN_MASK_RETVAL_CHECKS "RetValChecks"

## XN_RETURN_WITH_ERROR_LOG

#define XN_RETURN_WITH_ERROR_LOG | ( |  | pLogger,
|  |  | nRetVal,
|  |  | csFormat,
|  |  | ... )

Value:
XN_RETURN_WITH_LOG(pLogger, nRetVal, XN_LOG_ERROR, csFormat, __VA_ARGS__)
XN_RETURN_WITH_LOG
#define XN_RETURN_WITH_LOG(pLogger, nRetVal, severity, csFormat,...)
Definition XnLog.h:276
XN_LOG_ERROR
@ XN_LOG_ERROR
Definition XnLogTypes.h:47

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

## XN_RETURN_WITH_LOG

#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

## XN_RETURN_WITH_WARNING_LOG

#define XN_RETURN_WITH_WARNING_LOG | ( |  | pLogger,
|  |  | nRetVal,
|  |  | csFormat,
|  |  | ... )

Value:
XN_RETURN_WITH_LOG(pLogger, nRetVal, XN_LOG_WARNING, csFormat, __VA_ARGS__)
XN_LOG_WARNING
@ XN_LOG_WARNING
Definition XnLogTypes.h:46

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

## xnLoggerClose

#define xnLoggerClose | ( |  | pLogger | ) |

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

Closes a logger and NULLs the handle.

Parameters

  pLogger | [in] The logger to be closed.

## xnLoggerError

#define xnLoggerError | ( |  | pLogger,
|  |  | csFormat,
|  |  | ... )

Value:
xnLoggerWriteHelper(pLogger, XN_LOG_ERROR, csFormat, __VA_ARGS__)
xnLoggerWriteHelper
#define xnLoggerWriteHelper(pLogger, severity, csFormat,...)
Definition XnLog.h:245

Helper macro for logging. Issues an error log entry.

## xnLoggerInfo

#define xnLoggerInfo | ( |  | pLogger,
|  |  | csFormat,
|  |  | ... )

Value:
xnLoggerWriteHelper(pLogger, XN_LOG_INFO, csFormat, __VA_ARGS__)
XN_LOG_INFO
@ XN_LOG_INFO
Definition XnLogTypes.h:45

Helper macro for logging. Issues an info log entry.

## xnLoggerVerbose

#define xnLoggerVerbose | ( |  | pLogger,
|  |  | csFormat,
|  |  | ... )

Value:
xnLoggerWriteHelper(pLogger, XN_LOG_VERBOSE, csFormat, __VA_ARGS__)
XN_LOG_VERBOSE
@ XN_LOG_VERBOSE
Definition XnLogTypes.h:44

Helper macro for logging. Issues a verbose log entry.

## xnLoggerWarning

#define xnLoggerWarning | ( |  | pLogger,
|  |  | csFormat,
|  |  | ... )

Value:
xnLoggerWriteHelper(pLogger, XN_LOG_WARNING, csFormat, __VA_ARGS__)

Helper macro for logging. Issues a warning log entry.

## xnLoggerWriteHelper

#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

## xnLogClose()

XN_C_API XnStatus XN_C_DECL xnLogClose | ( |  | ) |

This function closes the log.

## xnLogCreateNewFile()

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

## xnLoggerIsEnabled()

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.

## xnLoggerOpen()

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.

## xnLoggerWrite()

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.

## xnLoggerWriteBinaryData()

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

## xnLoggerWriteNoEntry()

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

## xnLogGetFileName()

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

## xnLogGetMaskMinSeverity()

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.

## xnLogInitFromINIFile()

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.

## xnLogInitFromXmlFile()

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.

## xnLogInitSystem()

XN_C_API XnStatus XN_C_DECL xnLogInitSystem | ( |  | ) |

This function initializes the log system.

## xnLogRegisterLogWriter()

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

## xnLogSetConsoleOutput()

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.

## xnLogSetFileOutput()

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.

## xnLogSetLineInfo()

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

## xnLogSetMaskMinSeverity()

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.

## xnLogSetOutputFolder()

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

## xnLogStartNewFile()

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)

## xnLogUnregisterLogWriter()

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_LOGGER_RETVAL_CHECKS

XnLogger* XN_LOGGER_RETVAL_CHECKS