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