OpenNI 1.5.4: XnLog.h File Reference

OpenNI

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 XnLoggerXN_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

Generated on Wed May 16 2012 10:16:05 for OpenNI 1.5.4 by   doxygen 1.7.5.1