Core Logger

Detailed Description

Processes wide logger API.

Unless explicitly specified, all errors returned by DriveWorks APIs are non recoverable and the user application should transition to fail safe mode. In addition, any error code not described in this documentation should be consider as fatal and the user application should also transition to fail safe mode.

Data Structures
struct	dwLoggerMessage

Typedefs
typedef struct dwContextObject const *	dwConstContextHandle_t
typedef struct dwContextObject *	dwContextHandle_t
typedef void(*	dwLogCallback) (dwContextHandle_t context, dwLoggerVerbosity type, char8_t const *msg)
	Defines a user callback method called by the SDK to log the output. More...
typedef void(*	dwLoggerCallback) (dwLoggerMessage const *msg)
	Defines a user callback method called by the SDK to log the output with meta-data. More...

Enumerations
enum	dwLoggerVerbosity {   DW_LOG_VERBOSE = 0x0000 ,   DW_LOG_DEBUG = 0x1000 ,   DW_LOG_INFO = 0x2000 ,   DW_LOG_WARN = 0x3000 ,   DW_LOG_ERROR = 0x4000 ,   DW_LOG_SILENT = 0x7000 }
	Holds the verbosity level. More...

Functions
DW_API_PUBLIC dwStatus	dwLogger_enableTimestamps (bool const enabled)
	Enable or disable logging of timestamps before each message. More...
DW_API_PUBLIC dwStatus	dwLogger_initialize (dwLogCallback msgCallback)
	Creates a new logger instance. More...
DW_API_PUBLIC dwStatus	dwLogger_initializeExtended (dwLoggerCallback msgCallback)
	Creates a new logger instance that provides meta-data with the message. More...
DW_API_PUBLIC dwStatus	dwLogger_log (dwConstContextHandle_t const context, dwLoggerVerbosity const verbosity, char8_t const *const msg)
	Logs message. More...
DW_API_PUBLIC dwStatus	dwLogger_logExtended (const dwLoggerMessage *msg)
	Logs message. More...
DW_API_PUBLIC dwStatus	dwLogger_release (void)
	Release logger instance and free up used memory. More...
DW_API_PUBLIC dwStatus	dwLogger_setLogLevel (dwLoggerVerbosity const verbosity)
	Sets the verbosity level of the logger instance. More...
DW_API_PUBLIC dwStatus	dwLogger_setThreadId (char8_t const *threadId)
	Set the name of the current thread that will be returned when using extended logger. More...

---

Data Structure Documentation

dwLoggerMessage

struct dwLoggerMessage

Data Fields
char8_t const *	fileName	file name from where message was logged
int32_t	lineNum	line number where log originated from
char8_t const *	msg	message to log
char8_t const *	tag	name used to group related logs
char8_t const *	threadId	identifier for thread
dwLoggerVerbosity	verbosity	how severe is the log

Typedef Documentation

dwConstContextHandle_t

typedef struct dwContextObject const* dwConstContextHandle_t

Definition at line 67 of file Logger.h.

dwContextHandle_t

typedef struct dwContextObject* dwContextHandle_t

Definition at line 65 of file Logger.h.

dwLogCallback

typedef void(* dwLogCallback) (dwContextHandle_t context, dwLoggerVerbosity type, char8_t const *msg)

Defines a user callback method called by the SDK to log the output.

Parameters

[in]	context	Deprecated context pointer, set to DW_NULL_HANDLE. Should not be used
[in]	type	Specifies the type of message being logged.
[in]	msg	A pointer to the message.

Definition at line 98 of file Logger.h.

dwLoggerCallback

typedef void(* dwLoggerCallback) (dwLoggerMessage const *msg)

Defines a user callback method called by the SDK to log the output with meta-data.

Parameters

[in]

msg

A struct containing message and meta-data

Definition at line 105 of file Logger.h.

Enumeration Type Documentation

dwLoggerVerbosity

enum dwLoggerVerbosity

Holds the verbosity level.

Enumerator
DW_LOG_VERBOSE	Log everything, default log level.
DW_LOG_DEBUG	Log Debug information.
DW_LOG_INFO	Log Notice information.
DW_LOG_WARN	Log Warning information.
DW_LOG_ERROR	Log Error information.
DW_LOG_SILENT	Log nothing.

Definition at line 72 of file Logger.h.

Function Documentation

dwLogger_enableTimestamps()

DW_API_PUBLIC dwStatus dwLogger_enableTimestamps

(

bool const

enabled

)

Enable or disable logging of timestamps before each message.

dwLogger is initialized with timestamps enabled.

Parameters

[in]

enabled

Whether to log timestamps (true) or not (false).

Returns

DW_SUCCESS always.

dwLogger_initialize()

DW_API_PUBLIC dwStatus dwLogger_initialize

(

dwLogCallback

msgCallback

)

Creates a new logger instance.

The initialization behavior of the logger is as follows. If the logger is initialized with dwLogger_initializeExtended, then the dwLoggerCallback provided to that function will be used. If the logger is initialized with dwLogger_initialize, then the dwLogCallback provided to that function will be used. If the logger is initialized with both functions, then the function provided to dwLogger_initializeExtended will take precedence

Parameters

[in]

msgCallback

Specifies the callback method used by the SDK to pass log messages. It must be thread-safe.

Return values

DW_INVALID_ARGUMENT	if msgCallback is NULL. Provide a valid input parameter.
DW_FAILURE	if the logger verbosity is invalid. Provide a valid verbosity level.
DW_SUCCESS

dwLogger_initializeExtended()

DW_API_PUBLIC dwStatus dwLogger_initializeExtended

(

dwLoggerCallback

msgCallback

)

Creates a new logger instance that provides meta-data with the message.

The initialization behavior of the logger is as follows. If the logger is initialized with dwLogger_initializeExtended, then the dwLoggerCallback provided to that function will be used. If the logger is initialized with dwLogger_initialize then the dwLogCallback provided to that function will be used. If the logger is initialized with both functions, then the function provided to dwLogger_initializeExtended will take precedence

Parameters

[in]

msgCallback

Specifies the callback method used by the SDK to pass log messages. It must be thread-safe.

Return values

DW_INVALID_ARGUMENT	if msgCallback is NULL. Provide a valid input parameter.
DW_FAILURE	if the logger verbosity is invalid. Provide a valid verbosity level.
DW_SUCCESS

dwLogger_log()

DW_API_PUBLIC dwStatus dwLogger_log	(	dwConstContextHandle_t const	context,
		dwLoggerVerbosity const	verbosity,
		char8_t const *const	msg
	)

Logs message.

if an extended callback has been initialized then it will return default values for parameters not provided
tag will be "NO_TAG"
fileName will be ""
lineNum will be 0
threadId will be ""

Parameters

[in]	context	Specifies the DriveWorks context that generated this message.
[in]	verbosity	Specifies the verbosity level to use.
[in]	msg	Specifies message which is to be logged.

Return values

DW_FAILURE	if verbosity parameter is not inside the dwLoggerVerbosity enum OR if msg is a null pointer.
DW_SUCCESS	if no issues are encountered.

dwLogger_logExtended()

DW_API_PUBLIC dwStatus dwLogger_logExtended

(

const dwLoggerMessage *

msg

)

Logs message.

Parameters

[in]

msg

Specifies message to be logged with additional meta-data

Return values

DW_INVALID_ARGUMENT	if verbosity is invalid
DW_FAILURE	if the function clock_gettime() fails
DW_SUCCESS

dwLogger_release()

DW_API_PUBLIC dwStatus dwLogger_release

(

void

)

Release logger instance and free up used memory.

Returns

DW_SUCCESS always.

dwLogger_setLogLevel()

DW_API_PUBLIC dwStatus dwLogger_setLogLevel

(

dwLoggerVerbosity const

verbosity

)

Sets the verbosity level of the logger instance.

Any messages with higher or equal verbosity level is forwarded to the logger callback.

Parameters

[in]

verbosity

Specifies the verbosity level to use.

Return values

DW_INVALID_ARGUMENT	if verbosity is invalid. Provide a valid verbosity level.
DW_SUCCESS

dwLogger_setThreadId()

DW_API_PUBLIC dwStatus dwLogger_setThreadId

(

char8_t const *

threadId

)

Set the name of the current thread that will be returned when using extended logger.

Thread id should be set prior to calling any other DW function to avoid confusion
If this function is not called the logger uses an incrementing counter by default
Truncates after 64 characters

Parameters

[in]

threadId

Specifies name of the current thread

Return values

DW_SUCCESS