	QSDK 1.1 Documentation

Utils::Log Struct Reference
[Logging]

#include <Q/dpf.h>

Inheritance diagram for Utils::Log:

List of all members.


Public Member Functions
bool	enabled () const
bool	enabled (unsigned int category) const
int	level () const
int	level (unsigned int category) const
unsigned int	verbosity () const
unsigned int	verbosity (unsigned int category) const
Logger *	logger (MessageClass cls) const
void	setLevel (int level)
void	setLevel (unsigned int category, int level)
void	setEnabled (bool enabled)
void	setEnabled (unsigned int category, bool enabled)
void	setVerbosity (unsigned int verbosity)
void	setVerbosity (unsigned int category, unsigned int verbosity)
void	setLogger (Logger *logger)
void	setLogger (MessageClass cls, Logger *logger)
const char *	getCategory (unsigned int cat)
void	resetLogStats ()
void	logStats (unsigned int &errors, unsigned int &warnings, unsigned int &infos, unsigned int &debugs)

unsigned int	getCategory (const char *name, int level, bool enabled)
unsigned int	getCategory (const char *name, int level, bool enabled, unsigned int verbosity)
unsigned int	getCategory (const char *name)

void	print (MessageClass cls, unsigned int category, int level, const char file, unsigned int line, const char format,...)
void	vprint (MessageClass cls, unsigned int category, int level, const char file, unsigned int line, const char format, const va_list &args)
void	print (MessageClass cls, const char category, int level, const char file, unsigned int line, const char *format,...)
void	vprint (MessageClass cls, const char category, int level, const char file, unsigned int line, const char *format, const va_list &args)

bool	willPrint (MessageClass cls, unsigned int category, int level)
bool	willPrint (MessageClass cls, const char *category, int level)
Static Public Member Functions
Log *	theLog ()
Logger::REF	theDefaultLogger ()

Detailed Description

The singleton Log object is used to record informational, debug and error messages generated both internally by the Q system and (optionally) externally by users of the Q system. Messages are grouped into categories and each message has a numeric level associated with it. This allows users of the logging infrastructure to filter the log so as to receive only messages that are relevant to a single subsystem. Log levels are small integers; the larger the log level of a message is, the less important it is. A user of the logging system can cut down the number of messages logged to a category by setting the level of that category to a smaller number. All messages in a category can be suppressed by setting the log level to -1.

For efficiency, categories are represented by small positive integers. New categories can be created by calling getCategory() with the name of the category and any initial state for the category. If the initial state is not specified, the log maintains a set of global defaults for initialising new categories.

Each category has 3 variables associated with it:

An enabled flag which can be used to globally enable/disable messages from the category.
A level which is used to filter log messages based on their detail level. Only messages with level less than or equal to the category's level are logged.
A verbosity which determines the amount of information logged by a single message. For instance, a message logged in the category foo at log level 1 with the message string "Message" would look like this for the three different supported values of verbosity.

 0   debug[1]|foo|Message
 1   debug[1]|foo|file.cpp:1234|Message
 2   debug[1]|foo|file.cpp:1234|<time>|<taskid>|Message

Informational, Warning and Error messages are logged at levels -1, -2 and -3 respectively and to avoid confusion in this case, the messages are prefixed with "info", "warning" or "error" and the level is omitted.

Each message also has a message class. The message class is defined by enumerated type Utils::MessageClass.

The logging system can be further controlled by configuration settings (using the Registry on Windows, or a text file on Unix). The settings may be edited using the supplied utility QSettings.

See also:: Q::LogLayer

Member Function Documentation

bool Utils::Log::enabled ( unsigned int category ) const

Return values:

true if an individual category is enabled.

bool Utils::Log::enabled ( ) const [inline]

Returns the default enabled flag for new categories

const char* Utils::Log::getCategory ( unsigned int cat )

Return the name of a category if it exists or zero otherwise.

unsigned int Utils::Log::getCategory ( const char * name )

Find or create the category with the given name. If it doesn't exist it is created with the given initial state (or the current default state where appropriate).

unsigned int Utils::Log::getCategory ( const char * name,

int level,

bool enabled,

unsigned int verbosity

)

Find or create the category with the given name. If it doesn't exist it is created with the given initial state (or the current default state where appropriate).

unsigned int Utils::Log::getCategory ( const char * name,

int level,

bool enabled

)

Find or create the category with the given name. If it doesn't exist it is created with the given initial state (or the current default state where appropriate).

int Utils::Log::level ( unsigned int category ) const

Returns the log level of a specified category.

int Utils::Log::level ( ) const [inline]

Returns the default log level for new categories.

Logger* Utils::Log::logger ( MessageClass cls ) const

Returs the current logger used for the given MessageClass.

void Utils::Log::logStats ( unsigned int & errors,

unsigned int & warnings,

unsigned int & infos,

unsigned int & debugs

)

Return the number of messages logged in the various message classes.

void Utils::Log::print ( MessageClass cls,

const char * category,

int level,

const char * file,

unsigned int line,

const char * format,

...

)

Print a message with the given class, category and level. The values passed for file and line should be the filename and line number of the code printing the message. The message itself is specified as a printf-like format string and a variable list of arguments.

void Utils::Log::print ( MessageClass cls,

unsigned int category,

int level,

const char * file,

unsigned int line,

const char * format,

...

)

Print a message with the given class, category and level. The values passed for file and line should be the filename and line number of the code printing the message. The message itself is specified as a printf-like format string and a variable list of arguments.

void Utils::Log::resetLogStats ( )

Clear the current counters of messages logged.

void Utils::Log::setEnabled ( unsigned int category,

bool enabled

)

Set the enabled flag on category to enabled.

void Utils::Log::setEnabled ( bool enabled )

Set both the default enabled flag for new categories and the enabled flag on all existing categories.

void Utils::Log::setLevel ( unsigned int category,

int level

)

Set the log level of category to level.

void Utils::Log::setLevel ( int level )

Set both the default log level for new categories and the log level of all existing categories.

void Utils::Log::setLogger ( MessageClass cls,

Logger * logger

)

Set the logging channel for messages of the given class. Messages sent to the log are formatted and then passed onto the configured logger, allowing applications to implement custom loggers to fit status messages into their own user interface, for instance.

void Utils::Log::setLogger ( Logger * logger )

Set the logging channel for all categories. Messages sent to the log are formatted and then passed onto the configured logger, allowing applications to implement custom loggers to fit status messages into their own user interface, for instance.

void Utils::Log::setVerbosity ( unsigned int category,

unsigned int verbosity

)

Set the verbosity level for category to verbosity.

void Utils::Log::setVerbosity ( unsigned int verbosity )

Set both the default verbosity level for new categories and the verbosity level of all existing categories.

Logger::REF Utils::Log::theDefaultLogger ( ) [static]

Return the default logging channel.

Log* Utils::Log::theLog ( ) [static]

Return the single global instance of the Log.

unsigned int Utils::Log::verbosity ( unsigned int category ) const

Returns the verbosity level of a category

unsigned int Utils::Log::verbosity ( ) const [inline]

Returns the default verbosity level for new categories

void Utils::Log::vprint ( MessageClass cls,

const char * category,

int level,

const char * file,

unsigned int line,

const char * format,

const va_list & args

)

Print a message with the given class, category and level. The values passed for file and line should be the filename and line number of the code printing the message. The message itself is specified as a printf-like format string and a variable list of arguments.

void Utils::Log::vprint ( MessageClass cls,

unsigned int category,

int level,

const char * file,

unsigned int line,

const char * format,

const va_list & args

)

Print a message with the given class, category and level. The values passed for file and line should be the filename and line number of the code printing the message. The message itself is specified as a printf-like format string and a variable list of arguments.

bool Utils::Log::willPrint ( MessageClass cls,

const char * category,

int level

)

Return true if a message with the given category and level would be printed.

bool Utils::Log::willPrint ( MessageClass cls,

unsigned int category,

int level

)

Return true if a message with the given category and level would be printed.

Utils::Log Struct Reference [Logging]

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

Utils::Log Struct Reference
[Logging]