Detailed Description

v1.20 (30 April 2023)
The Log module includes the Log Manager and Log for handling the logs output of the application and the GDK itself.

The Log Manager handles the creation/destruction of Log Objects and always owns a default log named "default" although it is not initialized.
All CRM64Pro GDK modules use this default log for messages and information output.

The client application can use the default log or create any number of additional log objects using the Log Manager.
A good practice is to initialize the default log using Log::init() right after Main::Instance() in order to capture all the GDK initialization messages.
The default log can not be released, and once initialized you can stop the log output using Log::pause() method.

There is an useful mode where all the return error codes are logged automatically using the default log if you link against a GDK debug version and set eLogLevel to LL_HIGH.

This is a standard manager: objects are not shared and must be unique using its name as the key, in other words, you can not create an object with the same name of another one already created.

Only a single instance of the Log Manager exists which is created once Main is instantiated.
You can get a reference to this manager using Main::ILogMgr() method.

Note: The Log Manager and default Log are automatically released when Main::Terminate() is called.
At this time, any resource still loaded, will be released avoding resource leaks.

Classes
class	CRM64Pro::Log
	Log Object class. More...

class	CRM64Pro::LogMgr
	Log Manager class. More...

Macros
#define	LM_NULL 0

#define	LM_FILE 2

#define	LM_FILEAPPEND 4

#define	LM_STDOUT 8

#define	LM_CONSOLE 16

#define	LM_RESERVED 64

Enumerations
enum	CRM64Pro::eLogLevel { CRM64Pro::LL_LOW = 0 , CRM64Pro::LL_NORMAL = 4 , CRM64Pro::LL_HIGH = 16 }
	The log level detail. More...

enum	CRM64Pro::eLogMessageLevel { CRM64Pro::LML_CRITICAL = 0 , CRM64Pro::LML_NORMAL = 4 , CRM64Pro::LML_LOW = 16 , CRM64Pro::LML_INFO = 64 , CRM64Pro::LML_NULL = 128 }
	The importance of a logged message. More...

Functions
Sint32	CRM64Pro::Log::info (Sint32 iMode=0)
	Request log object information.

Sint32	CRM64Pro::Log::getName (string &sName)
	Get the name.

Uint32	CRM64Pro::Log::getID ()
	Get the ID.

Sint32	CRM64Pro::Log::init (const string &sAppname, eLogLevel eLL, Sint32 iLM, const string &sFilename="", const string &sAuthor="", const string &sEmail="", const string &sWeb="")
	Initialize a log.

Sint32	CRM64Pro::Log::pause ()
	Pause the log.

Sint32	CRM64Pro::Log::resume ()
	Resume a paused log.

Sint32	CRM64Pro::Log::status ()
	Get the log status.

Sint32	CRM64Pro::Log::msg (eLogMessageLevel eLML, char *szFmt,...)
	Output a message.

eLogLevel	CRM64Pro::Log::getLogLevel ()
	Get the log detail level.

Sint32	CRM64Pro::Log::getLogMode ()
	Get the log mode.

Sint32	CRM64Pro::Log::setLogMode (Sint32 iLM, const string &sFilename="")
	Set the log mode.

Sint32	CRM64Pro::Log::getFilename (string &sName)
	Get the filename.

Sint32	CRM64Pro::Log::setTimeStamp (Sint32 iM)
	Print the time stamp for each logged message.

Sint32	CRM64Pro::Log::getTimeStamp ()
	Get the time stamp mode.

Sint32	CRM64Pro::LogMgr::info (Sint32 iMode=0)
	Request Log Manager information.

Sint32	CRM64Pro::LogMgr::create (const string &sName, Uint32 iUnused=0)
	Creates a new log.

Sint32	CRM64Pro::LogMgr::close (Sint32 idLog)
	Close and destroy a log.

Sint32	CRM64Pro::LogMgr::getNum ()
	Get number of loaded objects.

Sint32	CRM64Pro::LogMgr::setName (Sint32 idLog, const string &sName)
	Change the object name.

Log *	CRM64Pro::LogMgr::get (Sint32 idLog=0)
	Get a pointer to the log using its handler.

Macro Definition Documentation

◆ LM_NULL

#define LM_NULL 0

Log output mode. 'lm' parameter in CRM64Pro::Log::init(), no output at all.

◆ LM_FILE

#define LM_FILE 2

Log output mode. 'lm' parameter in CRM64Pro::Log::init(), output to a file, if it already exists, its contents are destroyed.

◆ LM_FILEAPPEND

#define LM_FILEAPPEND 4

Log output mode. 'lm' parameter in CRM64Pro::Log::init(), output to a file, if it already exists, we write at the file end.

◆ LM_STDOUT

#define LM_STDOUT 8

Log output mode. 'lm' parameter in CRM64Pro::Log::init, output to standard output stream (stdout).

◆ LM_CONSOLE

#define LM_CONSOLE 16

Log output mode. 'lm' parameter in CRM64Pro::Log::init(), output to integrated and default console.

◆ LM_RESERVED

#define LM_RESERVED 64

Log output mode. 'lm' parameter in CRM64Pro::Log::init(), reserved for internal usage, do not use it.

Enumeration Type Documentation

◆ eLogLevel

enum CRM64Pro::eLogLevel

The log level detail.

Enumerator
LL_LOW	'll' parameter in Log::init(), only LML_CRITICAL and LML_INFO messages are logged out.
LL_NORMAL	'll' parameter in Log::init(), previous level messages plus LML_NORMAL are logged out.
LL_HIGH	'll' parameter in Log::init(), previous level messages plus LML_LOW are logged out.

◆ eLogMessageLevel

enum CRM64Pro::eLogMessageLevel

The importance of a logged message.

Enumerator
LML_CRITICAL	'lml' parameter in Log::msg(), logged on all log levels. Used for critical errors.
LML_NORMAL	'lml' parameter in Log::msg(), logged on LL_NORMAL and LL_HIGH levels. Used for errors and warnings.
LML_LOW	'lml' parameter in Log::msg(), logged on LL_HIGH level. Used for warning and debugging messages.
LML_INFO	'lml' parameter in Log::msg(), logged on all log levels. Timestamp is not supported. Used for logging information messages.
LML_NULL	'lml' parameter in Log::msg(), dont log anyting.

Function Documentation

◆ info() [1/2]

Sint32 CRM64Pro::Log::info ( Sint32 iMode = 0 )

Request log object information.

For displaying the information, it uses the default log.

Parameters

iMode unused for the time being.

Returns: 0 on success or a negative error code on failure.

◆ getName()

Sint32 CRM64Pro::Log::getName ( string & sName )

Get the name.

Parameters

sName a string containing the log name.

Returns: 0 on success or a negative error code on failure.

◆ getID()

Uint32 CRM64Pro::Log::getID ( )

Get the ID.

Returns: the object ID.

◆ init()

Sint32 CRM64Pro::Log::init	(	const string &	sAppname,
		eLogLevel	eLL,
		Sint32	iLM,
		const string &	sFilename = `""`,
		const string &	sAuthor = `""`,
		const string &	sEmail = `""`,
		const string &	sWeb = `""`
	)

Initialize a log.

Parameters

sAppname	name of your application.
eLL	log level detail. Check eLogLevel enum for further information.
iLM	log mode. Check LM_NULL, LM_STDOUT, LM_FILE, LM_FILEAPPEND and LM_CONSOLE for further information. You can OR'ed them.
sFilename	name of log file (only makes sense with LM_FILE or LM_FILEAPPEND). Directory separators '\' and '/' are supported.
sAuthor	application author name (none by default).
sEmail	email of author (none by default).
sWeb	web page of your application (none by default).

Returns: 0 on success or a negative error code on failure.

◆ pause()

Sint32 CRM64Pro::Log::pause ( )

Pause the log.

Log output is temporary disabled.

Returns: 0 on success or a negative error code on failure.

◆ resume()

Sint32 CRM64Pro::Log::resume ( )

Resume a paused log.

Log output is enabled.

Returns: 0 on success or a negative error code on failure.

◆ status()

Sint32 CRM64Pro::Log::status ( )

Get the log status.

Returns

C64_STATUS_DISABLED	log is disabled (no output).
C64_STATUS_ENABLED	log is enabled (output depending on the log mode).
C64_STATUS_PAUSED	log is enabled but is paused (no output).

◆ msg()

Sint32 CRM64Pro::Log::msg	(	eLogMessageLevel	eLML,
		char *	szFmt,
			...
	)

Output a message.

Parameters

eLML	importance of the message. Check eLogMessageLevel enum for further information.
szFmt	a printf() style message format string.
...	additional parameters matching % tokens in the fmt string, if any

Note: This method is thread-safe and internally uses a mutex.

Returns: 0 on success or a negative error code on failure.

◆ getLogLevel()

eLogLevel CRM64Pro::Log::getLogLevel ( )

Get the log detail level.

Returns: log detail level. Check eLogLevel enum for further information.

◆ getLogMode()

Sint32 CRM64Pro::Log::getLogMode ( )

Get the log mode.

Returns: log mode. Check LM_NULL, LM_STDOUT, LM_FILE, LM_FILEAPPEND and LM_CONSOLE for further information.

◆ setLogMode()

Sint32 CRM64Pro::Log::setLogMode	(	Sint32	iLM,
		const string &	sFilename = `""`
	)

Set the log mode.

Parameters

iLM	log mode. Check LM_NULL, LM_STDOUT, LM_FILE, LM_FILEAPPEND and LM_CONSOLE for further information.
sFilename	name of log file (only makes sense with LM_FILE or LM_FILEAPPEND). Directory separators '\' and '/' are supported.

Returns: 0 on success or a negative error code on failure.

Note: The log must be initialized (after a successful call to init()) or this method does nothing.
If the log was initialized with LM_FILE or LM_FILEAPPEND, we can not change the log file.

◆ getFilename()

Sint32 CRM64Pro::Log::getFilename ( string & sName )

Get the filename.

Parameters

sName a string variable.

Returns: 0 on success or a negative error code on failure.

◆ setTimeStamp()

Sint32 CRM64Pro::Log::setTimeStamp ( Sint32 iM )

Print the time stamp for each logged message.

By default, it is disabled.
It only works with LM_FILE or LM_FILEAPPEND modes.
It does not display any information to console system.

Parameters

iM	0 to disable it or any other value for enabling it.

Returns: 0 on success or a negative error code on failure.

◆ getTimeStamp()

Sint32 CRM64Pro::Log::getTimeStamp ( )

Get the time stamp mode.

Returns: 0 if it is disabled or any other value if it is enabled

◆ info() [2/2]

Sint32 CRM64Pro::LogMgr::info ( Sint32 iMode = 0 )

Request Log Manager information.

For displaying the information, it uses the default log.

Parameters

iMode -1 for displaying only Manager information.
0 for displaying Manager and all Objects information. This is the default value.
idLog for displaying Manager and given Log id information.

Returns: 0 on success or a negative error code on failure.

◆ create()

Sint32 CRM64Pro::LogMgr::create	(	const string &	sName,
		Uint32	iUnused = `0`
	)

Creates a new log.

Parameters

sName	The name to give to the log object (e.g. 'myLog'). The object name must be unique and with a maximum size of 64 characters or will be truncated.
iUnused	unused for the time being.

Returns: greater than 0 on success(the Log id) or a negative error code on failure.

◆ close()

Sint32 CRM64Pro::LogMgr::close ( Sint32 idLog )

Close and destroy a log.

Parameters

idLog 0 for closing all logs or the Log id.
The default log is automatically created and can not be removed with this method.

Returns: 0 on success or a negative error code on failure.

Note: If you forget to close a log, it will be automatically closed once the GDK is terminated.

◆ getNum()

Sint32 CRM64Pro::LogMgr::getNum ( )

Get number of loaded objects.

Returns: the number of log objects.

◆ setName()

Sint32 CRM64Pro::LogMgr::setName	(	Sint32	idLog,
		const string &	sName
	)

Change the object name.

Parameters

idLog	Log id.
sName	The name to give to the log object (e.g. 'myLog'). The object name must be unique and with a maximum size of 64 characters or will be truncated.

Returns: 0 on success or a negative error code on failure.

◆ get()

Log * CRM64Pro::LogMgr::get ( Sint32 idLog = 0 )

Get a pointer to the log using its handler.

Parameters

idLog Log id. With 0 (default value), it returns the default log.

Returns: nullptr the log was not found.; A pointer to the log object.

Detailed Description

Classes

Macros

Enumerations

Functions

Macro Definition Documentation

◆ LM_NULL

◆ LM_FILE

◆ LM_FILEAPPEND

◆ LM_STDOUT

◆ LM_CONSOLE

◆ LM_RESERVED

Enumeration Type Documentation

◆ eLogLevel

◆ eLogMessageLevel

Function Documentation

◆ info() [1/2]

◆ getName()

◆ getID()

◆ init()

◆ pause()

◆ resume()

◆ status()

◆ msg()

◆ getLogLevel()

◆ getLogMode()

◆ setLogMode()

◆ getFilename()

◆ setTimeStamp()

◆ getTimeStamp()

◆ info() [2/2]

◆ create()

◆ close()

◆ getNum()

◆ setName()

◆ get()