Description

Log Manager and Log objects for application and GDK message output [v26.02.0].

Overview

The Log module handles all logging output for both the client application and the GDK itself. The Log Manager handles the creation and destruction of Log objects and always owns a default log named "default" (although it is not initialized by default).
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.

Key features

Default log: Built-in "default" log used by all GDK modules
Multiple logs: Create additional Log objects for application-specific output
Pause control: Stop and resume log output without releasing the log
Debug mode: Automatic error code logging when using GDK debug builds
Color output: ANSI color coding for stdout output based on severity levels
Indentation: Automatic indentation management for structured output
Prefix characters: Customizable prefix characters for organized output blocks

Default log

The Log Manager always owns a default log named "default" with special characteristics:

Initialization	Not initialized by default; call Log::init() to enable output
GDK usage	All CRM64Pro GDK modules output messages through this log
Release protection	Cannot be released; use Log::pause() to stop output

Console Output Colors

When using LM_STDOUT, messages are automatically colored based on severity:

LL_CRITICAL	Bold Magenta - Fatal errors / Crashes
LL_ERROR	Red - Runtime errors
LL_WARNING	Yellow - Undesirable states
LL_INFO	Default - Standard messages
LL_DEBUG	Cyan - Diagnostic information
LL_TRACE	Dark Gray - Low-level execution details

Debug mode logging

An automatic error code logging mode is available when both conditions are met:

GDK version	Link against a GDK debug version
Log level	Set eLogLevel to LL_DEBUG

When enabled, all return error codes are automatically logged to the default log.

Structured Output

The log system supports automatic indentation management and prefix characters for organized output:

Indentation	Use pushIndent()/popIndent() to manage automatic spacing
Prefix characters	Use setPrefix()/clearPrefix() to add block markers like "\|" or ">>"
Combined usage	Combine prefix and indentation for clear hierarchical output

Manager type

This is a standard manager: objects are not shared and must be unique using its name as the key. You cannot create an object with the same name as another one already created.

Best practices

Initialize the default log using Log::init() right after Main::Instance() to capture all GDK initialization messages
Use Log::pause() instead of releasing when you need to temporarily stop default log output
Create separate Log objects for different application subsystems to organize output
Use debug builds with LL_DEBUG log level during development for comprehensive error tracking
Ensure each custom log has a unique name before creation
Access the manager exclusively through Main::ILogMgr()
Use pushIndent()/popIndent() pairs to create structured, readable log output
Use setPrefix() to mark logical blocks or sections with characters like "|" or ">>"
Always call clearPrefix() when done to avoid prefix leaking into subsequent messages

Note: The Log Manager and default Log are singletons, automatically created once Main is instantiated. You can get a reference to this manager using Main::ILogMgr() method.
The Log Manager is automatically released when Main::Terminate() is called. At this time, any resource still loaded will be released, avoiding resource leaks.

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

Enumerations
enum	CRM64Pro::eLogMode : Uint32 { CRM64Pro::LM_NULL = 0 , CRM64Pro::LM_FILE = 2 , CRM64Pro::LM_FILEAPPEND = 4 , CRM64Pro::LM_STDOUT = 8 , CRM64Pro::LM_CONSOLE = 16 , CRM64Pro::LM_RESERVED = 64 }
enum	CRM64Pro::eLogLevel { CRM64Pro::LL_OFF = 0 , CRM64Pro::LL_CRITICAL = 1 , CRM64Pro::LL_ERROR = 2 , CRM64Pro::LL_WARNING = 3 , CRM64Pro::LL_INFO = 4 , CRM64Pro::LL_DEBUG = 5 , CRM64Pro::LL_TRACE = 6 }
	Log levels. More...

Functions
bool	CRM64Pro::Log::info (Sint32 iMode=0) override
	Request Log object information.
const string &	CRM64Pro::Log::getName () const override
	Get the name.
Uint32	CRM64Pro::Log::getID () const override
	Get the ID.
bool	CRM64Pro::Log::init (const string &sAppname, eLogLevel eLL, eLogMode eLM, const string &sFilename="", const string &sAuthor="", const string &sEmail="", const string &sWeb="")
	Initialize the log object.
bool	CRM64Pro::Log::pause ()
	Disable log output temporarily.
bool	CRM64Pro::Log::resume ()
	Enable log output.
eGeneralStatus	CRM64Pro::Log::status () const
	Get log status.
bool	CRM64Pro::Log::msg (eLogLevel eLL, const char *szFmt,...)
	Write a message to the log.
eLogLevel	CRM64Pro::Log::getLogLevel ()
	Get log detail level.
eLogMode	CRM64Pro::Log::getLogMode () const
	Get log mode.
Sint32	CRM64Pro::Log::setLogMode (eLogMode eLM, const string &sFilename="")
	Set log mode.
const string &	CRM64Pro::Log::getFilename () const
	Get log filename.
bool	CRM64Pro::Log::setTimeStamp (bool bEnabled)
	Enable/disable timestamp in log messages.
bool	CRM64Pro::Log::getTimeStamp () const
	Get timestamp status.
bool	CRM64Pro::Log::pushIndent (Sint32 iSpaces=2)
	Push a new indentation level onto the stack.
bool	CRM64Pro::Log::popIndent ()
	Pop the most recent indentation level from the stack.
bool	CRM64Pro::Log::resetIndent ()
	Reset all indentation to zero.
Sint32	CRM64Pro::Log::getIndent () const
	Get the current total indentation level.
bool	CRM64Pro::Log::setPrefix (const char *szPrefix)
	Set a prefix character to be printed before each message.
bool	CRM64Pro::Log::clearPrefix ()
	Clear the prefix character.
bool	CRM64Pro::LogMgr::info (Sint32 iMode=0) override
	Request Log Manager information.
Sint32	CRM64Pro::LogMgr::create (const string &sName, Uint32 iUnused=0) override
	Create a new log object.
bool	CRM64Pro::LogMgr::close (Sint32 idLog) override
	Close and destroy a log object.
Sint32	CRM64Pro::LogMgr::getCount () const override
	Get number of loaded objects.
Sint32	CRM64Pro::LogMgr::setName (Sint32 idLog, const string &sName) override
	Change the object name.
Log *	CRM64Pro::LogMgr::get (Sint32 idLog=0)
	Get a pointer to the log object.

Enumeration Type Documentation

◆ eLogMode

enum CRM64Pro::eLogMode : Uint32

Log output modes used in Log::init() and Log::setLogMode().

Enumerator
LM_NULL	Log output mode for the 'lm' parameter in CRM64Pro::Log::init(). Disable output entirely.
LM_FILE	Log output mode for the 'lm' parameter in CRM64Pro::Log::init(). Output to a file and overwrite existing content.
LM_FILEAPPEND	Log output mode for the 'lm' parameter in CRM64Pro::Log::init(). Output to a file, appending to existing content.
LM_STDOUT	Log output mode for the 'lm' parameter in CRM64Pro::Log::init(). Output to standard output (stdout).
LM_CONSOLE	Log output mode for the 'lm' parameter in CRM64Pro::Log::init(). Output to the integrated default console.
LM_RESERVED	Log output mode reserved for internal use; do not use it.

◆ eLogLevel

enum CRM64Pro::eLogLevel

Log levels.

Enumerator
LL_OFF	Disable all logging.
LL_CRITICAL	Fatal errors, application crash, or assertions.
LL_ERROR	Runtime errors that do not require immediate termination.
LL_WARNING	Undesirable states or use of deprecated APIs.
LL_INFO	Runtime events (startup/shutdown). No-timestamp msgs.
LL_DEBUG	Detailed information for flow control.
LL_TRACE	Very detailed information, potentially high-volume.

Function Documentation

◆ info() [1/2]

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

override

Request Log object information.

Writes object information to the default log.

Parameters

iMode unused for the time being.

Returns: true on success or false on failure.

◆ getName()

const string & CRM64Pro::Log::getName ( ) const

override

Get the name.

Returns: The object name.

◆ getID()

Uint32 CRM64Pro::Log::getID ( ) const

override

Get the ID.

Returns: Object ID.

◆ init()

bool CRM64Pro::Log::init	(	const string &	sAppname,
		eLogLevel	eLL,
		eLogMode	eLM,
		const string &	sFilename = "",
		const string &	sAuthor = "",
		const string &	sEmail = "",
		const string &	sWeb = "" )

Initialize the log object.

Parameters

sAppname	Name of your application.
eLL	Log verbosity threshold. Messages with a severity level numerically higher than this will be ignored. See ::eLogLevel.
eLM	Log mode. See ::LM_NULL, ::LM_STDOUT, ::LM_FILE, ::LM_FILEAPPEND and ::LM_CONSOLE.
sFilename	Name of log file. Only used with ::LM_FILE or ::LM_FILEAPPEND. Directory separators '\' and '/' are supported.
sAuthor	Author name.
sEmail	Author email address.
sWeb	Author web site.

Returns: true on success or false on failure.

◆ pause()

bool CRM64Pro::Log::pause ( )

Disable log output temporarily.

Temporarily disables log output.

Returns: true on success or false on failure.

◆ resume()

bool CRM64Pro::Log::resume ( )

Enable log output.

Re-enables log output.

Returns: true on success or false on failure.

◆ status()

eGeneralStatus CRM64Pro::Log::status ( ) const

Get log status.

Returns: ::C64_STATUS_DISABLED if output is disabled, or ::C64_STATUS_ENABLED if output is enabled (actual output depends on log mode).

◆ msg()

bool CRM64Pro::Log::msg	(	eLogLevel	eLL,
		const char *	szFmt,
			... )

Write a message to the log.

Parameters

eLL	Severity level of the message. The message is logged only if this value is less than or equal to the verbosity set in init(). See ::eLogLevel.
szFmt	A printf() style message format string.
...	Variable arguments for format string.

Returns: true on success or false on failure.

◆ getLogLevel()

eLogLevel CRM64Pro::Log::getLogLevel ( )

Get log detail level.

Returns: Current log verbosity. See ::eLogLevel.

◆ getLogMode()

eLogMode CRM64Pro::Log::getLogMode ( ) const

Get log mode.

Returns: Current log mode. See ::LM_NULL, ::LM_STDOUT, ::LM_FILE, ::LM_FILEAPPEND and ::LM_CONSOLE.

◆ setLogMode()

Sint32 CRM64Pro::Log::setLogMode	(	eLogMode	eLM,
		const string &	sFilename = "" )

Set log mode.

Parameters

eLM	log mode. See ::LM_NULL, ::LM_STDOUT, ::LM_FILE, ::LM_FILEAPPEND and ::LM_CONSOLE.
sFilename	name of log file (only relevant with ::LM_FILE or ::LM_FILEAPPEND). Directory separators '\' and '/' are supported.

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

◆ getFilename()

const string & CRM64Pro::Log::getFilename ( ) const

Get log filename.

Returns: The current log filename.

◆ setTimeStamp()

bool CRM64Pro::Log::setTimeStamp ( bool bEnabled )

Enable/disable timestamp in log messages.

Disabled by default. Only works with ::LM_FILE or ::LM_FILEAPPEND modes. Does not display timestamps in console output.

Parameters

bEnabled true to enable or false to disable.

Returns: true on success or false on failure.

◆ getTimeStamp()

bool CRM64Pro::Log::getTimeStamp ( ) const

Get timestamp status.

Returns: true if enabled or false if disabled.

◆ pushIndent()

bool CRM64Pro::Log::pushIndent ( Sint32 iSpaces = 2 )

Push a new indentation level onto the stack.

Increases the current indentation by the specified number of spaces. Each call to pushIndent() should be paired with a corresponding popIndent(). Indentation is cumulative: multiple pushIndent() calls will add their spaces together.

Parameters

iSpaces Number of spaces to add to the current indentation level (default: 2).

Returns: true on success or false on failure.

◆ popIndent()

bool CRM64Pro::Log::popIndent ( )

Pop the most recent indentation level from the stack.

Decreases the current indentation by removing the last pushed indent level. Should be called to match each pushIndent() call.

Returns: true on success or false on failure.

◆ resetIndent()

bool CRM64Pro::Log::resetIndent ( )

Reset all indentation to zero.

Clears the entire indentation stack and resets current indentation to 0. Useful for recovering from mismatched push/pop calls or resetting state.

Returns: true on success or false on failure.

◆ getIndent()

Sint32 CRM64Pro::Log::getIndent ( ) const

Get the current total indentation level.

Returns the sum of all active indentation levels (total spaces).

Returns: Current indentation level in spaces.

◆ setPrefix()

bool CRM64Pro::Log::setPrefix ( const char * szPrefix )

Set a prefix character to be printed before each message.

Parameters

szPrefix String to print at the beginning of each message (e.g., "|", ">>", etc.). The prefix appears before indentation.

Returns: true on success or false on failure.

Note: The prefix remains active until clearPrefix() is called.

◆ clearPrefix()

bool CRM64Pro::Log::clearPrefix ( )

Clear the prefix character.

Returns: true on success or false on failure.

◆ info() [2/2]

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

override

Request Log Manager information.

Writes manager information to the default log.

Parameters

iMode -1 to display only manager information. 0 (default) to display manager and all objects. Specific object ID to display manager and only that object.

Returns: true on success or false on failure.

◆ create()

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

override

Create a new log object.

Parameters

sName	name for the log object (e.g. 'myLog'). Must be unique; longer names are truncated to 64 characters.
iUnused	unused for the time being.

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

◆ close()

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

override

Close and destroy a log object.

Parameters

idLog 0 to close all logs, or a specific log id. The default log cannot be removed with this method.

Returns: true if at least one log was closed, or false if none were closed.

Note: The default log (id=0) is ignored and will not be closed.

◆ getCount()

Sint32 CRM64Pro::LogMgr::getCount ( ) const

override

Get number of loaded objects.

Returns: Number of log objects.

◆ setName()

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

override

Change the object name.

Parameters

idLog	Log id.
sName	new name (e.g. 'myLog'). Must be unique; longer names are truncated to 64 characters.

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 object.

Parameters

idLog Log id. 0 (default) returns the default log.

Returns: nullptr if the log was not found, otherwise a pointer to the Log object.

Description

Overview

Key features

Default log

Console Output Colors

Debug mode logging

Structured Output

Manager type

Best practices

Classes

Enumerations

Functions

Enumeration Type Documentation

◆ eLogMode

◆ eLogLevel

Function Documentation

◆ info() [1/2]

◆ getName()

◆ getID()

◆ init()

◆ pause()

◆ resume()

◆ status()

◆ msg()

◆ getLogLevel()

◆ getLogMode()

◆ setLogMode()

◆ getFilename()

◆ setTimeStamp()

◆ getTimeStamp()

◆ pushIndent()

◆ popIndent()

◆ resetIndent()

◆ getIndent()

◆ setPrefix()

◆ clearPrefix()

◆ info() [2/2]

◆ create()

◆ close()

◆ getCount()

◆ setName()

◆ get()