Event Logger Interface

Contents

• 1. General
• 2. Design goals
• 3. Interface
• 4. Dependencies
• 5. Revisions

1. General

Event logger interface was introduced to define generic API to application event logger. Component-based design of the application requires that particular component has minimal knowledge about surrounding framework. Event logging functionality is specific to particular application and platform. Hence generic interface is required to hide an implementation.

2. Design goals

Interface was designed to generalize the following functionality and concepts:

• Message category scheme. Framework defines standard set of event logging categories: Fatal, Warning, Debug and Info. In addition, components may extend this list with new categories.
• Message category representation. Message category is primary defined as textual string. And in this form it is supposed to mark relevant output. Internally, category is represented as bit mask. Implementation provides a mapping between textual and binary representation of event category.
• Event logger implementation can be configured to allow only particular set of event categories to be logged. This gives the flexibility to customize logging depth as suitable for application user.
• Methods for logging textual and binary data. Every message is supplied with bound category.
• Binary data can be logged either in binary or encoded form.

Logging parameters substitution. One of important requirements for event logger is ability to dynamically modify output string, depending on number of formal parameters. Interface includes partial implementation of this via printf-like interface; but this functionality is left only for backward compatibility with existing applications. The choice was made to decouple parameter substitution functionality from event logger interface. Currently existing functionality is based on custom stream-based implementation, providing type-safety and convenient usage via overloaded shift operator. So all parameters are expected to be substituted before passing resulting buffer to event logger interface implementation.

3. Interface

Event logger interface defines the following types internally:

• ELogStatus - enumeration defines possible event logger exceptions. Also used as a type that can be thrown from event logger methods on logging error. Currently, following values are defined:
  • eOK - Used internally
  • eInvalidPathname - Specified path is not available
  • eSystemError - requested operation cannot be completed, due to system error returned.
• TBitmask - implementation-specific type, used as a bit mask for binary event category representation.
• TLogMessage - pair of bit mask and textual message body.

These methods return textual representation of event categories as defined by implementation:

• virtual const char* GetCategoryPrefix_Fatal() const = 0;
• virtual const char* GetCategoryPrefix_Warning() const = 0;
• virtual const char* GetCategoryPrefix_Debug() const = 0;
• virtual const char* GetCategoryPrefix_Info() const = 0;

This method performs mapping between textual representation of event categories and their binary representation. Additionally it registers allocated bit mask. If no more free bit masks available, zero is returned.

• virtual TBitmask ObtainCategoryCode(const char* _cpchCategoryName) = 0;

Following entry points define final logging functions:

• virtual void LogMessage(TBitmask _iPriorityID, const char* _cpchString,...) throw(ELogStatus) = 0; Method provides printf-style interface to event logger. Note that this approach is not type-safe and subsequent methods should be preferred.
• virtual void LogString(const TLogMessage& _p) throw(ELogStatus) = 0; Method writes specified message to application log, providing that logging is enabled for specified category. If logging is not enabled, message is discarded.
• virtual void LogString(TBitmask _iPriorityID, const char* _cpchString) throw(ELogStatus) = 0; Method is similar to above, it just uses other way of representing same data.
• virtual void LogRawData(TBitmask _iPriorityID, const char* _cpchRawBuffer, int _iLength) throw(ELogStatus) = 0; Method accepts an array of binary data and sends it as is to output media. Method may perform decoding of binary data into textual representation if destination cannot handle raw data.
• virtual void LogBinAsHex(TBitmask _iPriorityID, const char* _cpchRawBuffer, int _iLength) throw(ELogStatus) = 0; Method decodes supplied buffer of binary data and dumps it in human-readable representation.

4. Dependencies

There is no special requirements for this component, only C++ standard-compliant headers should be available.

5. Revisions