This is the documentation for Enlighten.

module Message Reporting and Error Handling

Classes

Name Description
Geo::GeoError

Description of a single error reported via an IGeoProgressProxy.

Geo::GeoProgress

Helper class to manage an IGeoProgressProxy.

Geo::IGeoProgressProxy

An interface for informing a client about the current progress of an operation.

Geo::TxtProgressBar

A simple implementation of an IGeoProgressProxy that uses printf to communicate with the user.

Functions

Name Description
DisplayPageInBrowser(const char *)

Display a text string, which should containing html, in the default browser.

GeoAttachLogger(GeoLogHandler, eGeoLogMsgTypeMask)

Attach a log handler which will be passed messages of the requested types.

GeoAttachSystemLoggers(eGeoLogContext, bool)

Attach a default set of system log handlers, appropriate to the content in which it is called.

GeoDetachAllLoggers(eGeoLogMsgTypeMask)

Detach all log handlers for the specified message types.

GeoDetachLogger(GeoLogHandler, eGeoLogMsgTypeMask)

Detach a previously attached log handler, it if was previously attached.

GeoIsLoggerAttached(eGeoLogMsgTypeMask)

Return true if at least one logger is attached for all of the specified message types.

GeoLogHandler_Debugger(eGeoLogMsgType, u32, const char *)

A log message handler for writing messages to the debugger output channel.

GeoLogHandler_Popup(eGeoLogMsgType, u32, const char *)

A log message handler for displaying messages in a popup box.

GeoLogHandler_Stdout(eGeoLogMsgType, u32, const char *)

A log message handler for writing messages to stdout.

GeoLogHandler_Stdout_SetOrigin(const char *)

To support the MS error message format (see http://tinyurl.com/6hm53bz) allow user to set an Origin, otherwise just leave empty.

GeoLogMsgType(eGeoLogMsgType, u32, char *)

It is convenient to have a textual label for a given channel easily available.

GeoPrintf(eGeoLogMsgType, u32, const char *, ...)

Messages are passed through the logger using a "printf()" like function.

GeoPrintf(eGeoLogMsgType, const char *, ...)

Messages are passed through the logger using a "printf()" like function.

GeoStageBegin(const char *)

Begin a statistics block.

GeoStageEnd()

End a statistics block.

GeoStatistic(const char *, Geo::s64)

Log a single statistic, as a name/value pair.

GeoStatistic(const char *, Geo::s32)

Log a single statistic, as a name/value pair.

GeoStatistic(const char *, Geo::u32)

Log a single statistic, as a name/value pair.

GeoStatistic(const char *, double)

Log a single statistic, as a name/value pair.

GeoStatistic(const char *, float)

Log a single statistic, as a name/value pair.

GeoStatistic(const char *, const char *)

Log a single statistic, as a name/value pair.

GeoStatistic(const char *, Geo::u64)

Log a single statistic, as a name/value pair.

GeoStatisticsBegin(const char *, const char *, const char *)

Begin a StatusXml file.

GeoStatisticsEnd()

End the StatusXml file (note that you may wish to set the filename to NULL after this)

GeoStatusLogHandler_XmlFile(eGeoLogMsgType, u32, const char *)

The event handler for the StatusXml file.

GeoStatusLogHandler_XmlFile_SetName(const char *, bool)

Set the name of the StatusXml file writer. If not called, no file is created.

GetTempFilename(GeoFileString &)

Get an absolute path to a temporary file you can open for reading/writing.

MakeGeoError(const char *, TPayload *)

Creates a GeoError struct by filling in the given error code, textual message and payload data.

MsgBox(Geo::eGeoLogMsgType, const char *)

Generate a popup window, indicating either an error or a warning otherwise.

MsgBox(Geo::eGeoLogMsgType, u32, const char *)

Generate a popup window, indicating either an error or a warning otherwise.

PrintError(const GeoError &)

Sends a GeoError object to the listeners attached to the GeoPrintf handlers.

PutTextOnWindowsClipBoard(const char *)

Puts text into the windows clipboard.

StopAndEnterDebugger()

Drop into the debugger.

Enums

Name Description
eGeoErrorSeverity

The severity of an error.

eGeoLogContext

enum eGeoLogContext

eGeoLogMsgType

enum eGeoLogMsgType

eGeoLogSystemState

enum eGeoLogSystemState

Typedefs

Name Description
u8 eGeoLogMsgTypeMask

A bit mask containing one or more message type flags.

bool(* GeoLogHandler)(eGeoLogMsgType msgType, u32 code, const char *msgText)

A log handler is a function which gets called when messages are passed using GeoPrintf().

s8 GeoLogHandlerCount

An internal handler count variable; signed because -1 is used to indicate an empty handler list.

Variables

Name Description
const GeoLogHandlerCount GEO_LOG_MAX_HANDLERS_PER_TYPE = 4

The maximum number of log handlers that can be installed per log message type.

const s32 GEO_LOG_MAX_MSG_LENGTH = 8192

Maximum length of a log message.

const s32 GEO_LOG_MSG_TYPE_MAX_LENGTH = 64

Minimum required buffer size needed for GeoLogMsgType().

const eGeoLogMsgType GEO_LOG_NUM_MSG_TYPE_INDEX[GEO_LOG_NUM_MSG_TYPES] = {LOG_INFO, LOG_DEBUG, LOG_STATUS, LOG_WARN, LOG_FATAL, LOG_ASSERT}

Define the order in which the message types are represented in internal data structures.

const u8 GEO_LOG_NUM_MSG_TYPES = 6

The number of types of log message.

const eGeoLogMsgTypeMask LOG_ALL = LOG_INFO | LOG_DEBUG | LOG_STATUS | LOG_WARN | LOG_FATAL | LOG_ASSERT

A bit mask for containing all the valid message types.

Defines

Name Description
GEO_ASSERT (void)0

Assert Handling: Please use the GEO_ASSERT() or GEO_ASSERT_MSG() macros in code, rather than calling CheckAssert() or CheckAssertMsg() directly.

GEO_ASSERT_MSG (void)0

Same as GEO_ASSERT, but adds an additional message string to the output.

GEO_ASSERT_REINTERPRET_ARRAY_CAST_OK GEO_ASSERT(GEO_SUBCLASS_OFFSET(CLS, SUB) == 0)

Check that a reinterpret_cast from CLS* to/from SUB* doesn't change the address.

GEO_VERIFY a

Always execute code and (when asserts are enabled) ensure that the return value is as expected.


bool GEO_CALL Geo::DisplayPageInBrowser


public: bool GEO_CALL DisplayPageInBrowser
(
    const char * htmlText
)


Display a text string, which should containing html, in the default browser.

Only implemented on windows platforms currently.


bool Geo::GeoAttachLogger


public: bool GeoAttachLogger
(
    GeoLogHandler logHandler,
    eGeoLogMsgTypeMask typeMask
)


Attach a log handler which will be passed messages of the requested types.

It returns true if it was successfully registered for all message types, otherwise a warning message is raised, and it returns false.


void Geo::GeoAttachSystemLoggers


public: void GeoAttachSystemLoggers
(
    eGeoLogContext context,
    bool nonInteractive
)


Attach a default set of system log handlers, appropriate to the content in which it is called.

Note, this has the side effect of enabling all the system loggers, even if they were previously disabled.


void Geo::GeoDetachAllLoggers


public: void GeoDetachAllLoggers
(
    eGeoLogMsgTypeMask typeMask
)


Detach all log handlers for the specified message types.


bool Geo::GeoDetachLogger


public: bool GeoDetachLogger
(
    GeoLogHandler logHandler,
    eGeoLogMsgTypeMask typeMask
)


Detach a previously attached log handler, it if was previously attached.

Returns true it if was detached, and false otherwise.


bool Geo::GeoIsLoggerAttached


public: bool GeoIsLoggerAttached
(
    eGeoLogMsgTypeMask typeMask
)


Return true if at least one logger is attached for all of the specified message types.


bool Geo::GeoLogHandler_Debugger


public: bool GeoLogHandler_Debugger
(
    eGeoLogMsgType msgType,
    u32 code,
    const char * msgText
)


A log message handler for writing messages to the debugger output channel.


bool Geo::GeoLogHandler_Popup


public: bool GeoLogHandler_Popup
(
    eGeoLogMsgType msgType,
    u32 code,
    const char * msgText
)


A log message handler for displaying messages in a popup box.


bool Geo::GeoLogHandler_Stdout


public: bool GeoLogHandler_Stdout
(
    eGeoLogMsgType msgType,
    u32 code,
    const char * msgText
)


A log message handler for writing messages to stdout.


void Geo::GeoLogHandler_Stdout_SetOrigin


public: void GeoLogHandler_Stdout_SetOrigin
(
    const char * filename
)


To support the MS error message format (see http://tinyurl.com/6hm53bz) allow user to set an Origin, otherwise just leave empty.


void Geo::GeoLogMsgType


public: void GeoLogMsgType
(
    eGeoLogMsgType type,
    u32 code,
    char * buffer
)


It is convenient to have a textual label for a given channel easily available.

The given buffer must be at least as long as GEO_LOG_MSG_TYPE_MAX_LENGTH.


bool Geo::GeoPrintf


public: bool GeoPrintf
(
    eGeoLogMsgType msgType,
    u32 code,
    const char * fmtStr,
    ...
)


Messages are passed through the logger using a "printf()" like function.

This function will always return true, unless any of the registered handlers return false. This is useful, for instance in the assert handler, where returning false indicates that the debugger should be entered.


bool Geo::GeoPrintf


public: bool GeoPrintf
(
    eGeoLogMsgType msgType,
    const char * fmtStr,
    ...
)


Messages are passed through the logger using a "printf()" like function.

This function will always return true, unless any of the registered handlers return false. This is useful, for instance in the assert handler, where returning false indicates that the debugger should be entered.


void GEO_CALL Geo::GeoStageBegin


public: void GEO_CALL GeoStageBegin
(
    const char * name
)


Begin a statistics block.


void GEO_CALL Geo::GeoStageEnd


public: void GEO_CALL GeoStageEnd()


End a statistics block.


void GEO_CALL Geo::GeoStatistic


public: void GEO_CALL GeoStatistic
(
    const char * name,
    Geo::s64 value
)


Log a single statistic, as a name/value pair.


void GEO_CALL Geo::GeoStatistic


public: void GEO_CALL GeoStatistic
(
    const char * name,
    Geo::s32 value
)


Log a single statistic, as a name/value pair.


void GEO_CALL Geo::GeoStatistic


public: void GEO_CALL GeoStatistic
(
    const char * name,
    Geo::u32 value
)


Log a single statistic, as a name/value pair.


void GEO_CALL Geo::GeoStatistic


public: void GEO_CALL GeoStatistic
(
    const char * name,
    double value
)


Log a single statistic, as a name/value pair.


void GEO_CALL Geo::GeoStatistic


public: void GEO_CALL GeoStatistic
(
    const char * name,
    float value
)


Log a single statistic, as a name/value pair.


void GEO_CALL Geo::GeoStatistic


public: void GEO_CALL GeoStatistic
(
    const char * name,
    const char * value
)


Log a single statistic, as a name/value pair.


void GEO_CALL Geo::GeoStatistic


public: void GEO_CALL GeoStatistic
(
    const char * name,
    Geo::u64 value
)


Log a single statistic, as a name/value pair.


void GEO_CALL Geo::GeoStatisticsBegin


public: void GEO_CALL GeoStatisticsBegin
(
    const char * taskName,
    const char * output,
    const char * version
)


Begin a StatusXml file.


void GEO_CALL Geo::GeoStatisticsEnd


public: void GEO_CALL GeoStatisticsEnd()


End the StatusXml file (note that you may wish to set the filename to NULL after this)


bool GEO_CALL Geo::GeoStatusLogHandler_XmlFile


public: bool GEO_CALL GeoStatusLogHandler_XmlFile
(
    eGeoLogMsgType msgType,
    u32 code,
    const char * msgText
)


The event handler for the StatusXml file.


void GEO_CALL Geo::GeoStatusLogHandler_XmlFile_SetName


public: void GEO_CALL GeoStatusLogHandler_XmlFile_SetName
(
    const char * filename,
    bool logInputOutput
)


Set the name of the StatusXml file writer. If not called, no file is created.


bool GEO_CALL Geo::GetTempFilename


public: bool GEO_CALL GetTempFilename
(
    GeoFileString & resultFilename
)


Get an absolute path to a temporary file you can open for reading/writing.

May fail due to permissions (unlikely), and only implemented under windows. Returns false on all other platforms


GeoError Geo::MakeGeoError


public: GeoError MakeGeoError
(
    const char * message,
    TPayload * pPayload
)


Creates a GeoError struct by filling in the given error code, textual message and payload data.

The severity of the error is automatically set using the severity defined in the payload class.


bool GEO_CALL Geo::MsgBox


public: bool GEO_CALL MsgBox
(
    Geo::eGeoLogMsgType msgType,
    const char * errorString
)


Generate a popup window, indicating either an error or a warning otherwise.


bool GEO_CALL Geo::MsgBox


public: bool GEO_CALL MsgBox
(
    Geo::eGeoLogMsgType msgType,
    u32 code,
    const char * errorString
)


Generate a popup window, indicating either an error or a warning otherwise.


void Geo::PrintError


public: void PrintError
(
    const GeoError & error
)


Sends a GeoError object to the listeners attached to the GeoPrintf handlers.

This is the simplest response you can have to a GeoError being raised.


bool GEO_CALL Geo::PutTextOnWindowsClipBoard


public: bool GEO_CALL PutTextOnWindowsClipBoard
(
    const char * text
)


Puts text into the windows clipboard.


void Geo::StopAndEnterDebugger


public: void StopAndEnterDebugger()


Drop into the debugger.


eGeoErrorSeverity


public: enum eGeoErrorSeverity
{
    ES_WARNING = 0,
    ES_FATAL = 1
}


The severity of an error.

enumerators
ES_WARNING
ES_FATAL


eGeoLogContext


public: enum eGeoLogContext
{
    LOG_CONTEXT_GFX,
    LOG_CONTEXT_TEXT
}


enum eGeoLogContext

When attaching a default set of system messages, we set up different things depending upon whether we are in graphic or command line mode.

enumerators
LOG_CONTEXT_GFX

Set up handlers for a graphics environment.

LOG_CONTEXT_TEXT

Set up handlers for a textual environment, such as would be needed for programs with a command line interface.


eGeoLogMsgType


public: enum eGeoLogMsgType
{
    LOG_INFO = 1,
    LOG_DEBUG = 2,
    LOG_STATUS = 4,
    LOG_WARN = 8,
    LOG_FATAL = 16,
    LOG_ASSERT = 32
}


enum eGeoLogMsgType

The message logger knows about different kinds of log message.

Messages are expected to be formatted for output, and in particular should contain trailing line feed characters ("\n") where necessary. It is up to a particular logger handler to translate these into the correct convention for it's use, for example replacing "\n" with "\r\n" when writing to Windows files.

Note: If you add new message remember to preinitialise the LastLogHandler[] array as this will be missed by the compiler! Note: These should be arranged in the order of the frequency at which each message type is expected to be generated, with more frequent first.

enumerators
LOG_INFO

General messages: general information, and other output messages.

LOG_DEBUG

Debug messages: specifically to aid development, usually stripped from release code.

LOG_STATUS

Status messages: specific formatting to enable later processing, used for timing/etc.

LOG_WARN

Warning messages: should be paid attention to, but the program usually continues.

LOG_FATAL

Critical messages: error messages, usually generated to indicate why the program cannot proceed.

LOG_ASSERT

Assert message text: caused by an assertion failure.


eGeoLogSystemState


public: enum eGeoLogSystemState
{
    LOG_DISABLED,
    LOG_ENABLED
}


enum eGeoLogSystemState

The system loggers can operate in a number of different states. This enables their behaviour to be controlled, without having to uninstall them.

enumerators
LOG_DISABLED

System handlers should be switched off.

LOG_ENABLED

System handlers should be switched on.