Binaryworld - Working with NT EventLog - Part 1 (Introduction, Event Source, Message ... [ VB -> WinNT ]

<< Previous Article | Next Article >>

In this series of articles you will learn everything you need to build VB class to handle EventLog. Unfortunately in VB6 there is no inbuilt functionality to get full power of EventLog. VB6 has 2 functions App.StartLogging and App.LogEvent to get partial functionaly of logging. This function Log events as VBRuntimes so when you view events in Event Viewer then source of your entries will appear as VBRuntimes. Another limitation of LogEvent function is by default all entries will goto Application Log. In this article I will explain you how to wrap all Event Logging API in a single class to make it extremly simple to use. Some of the features of this class listed as below

Create/Delete Event Source With EventMessageFile, CategoryMessageFile and ParameterMessageFile
Write to Local/Remote EventLog
Read from Local/Remote EventLog
Clear EventLog
Backup EventLog

NOTE: Event Logging functionality is available only with Windows NT/XP/2k/2003 so this article is not intended for Windos 9x/ME Platform.

Lets start with Introduction of NT EventLog.

Introduction

Under Windows NT your application can write some criticle warings/errors or any helpful information to EventLog so later on Administrators or any other user can view errors/warnings or information logged in EventLog which can provide useful information in case of some criticle system problems (i.e. low-memory conditions, backup failed, service started/stopped by user...etc).

NT EventLog has 5 type of events which you can write to EventLog. You can specify any of the following types when you write to eventlog.

Error : An event that indicates a significant problem such as loss of data or loss of functionality. For example, if a service fails to load during startup, an Error event is logged.
Warning : An event that is not necessarily significant, but may indicate a possible future problem. For example, when disk space is low, a Warning event is logged. If an application can recover from an event without loss of functionality or data, it can generally classify the event as a warning event.
Information : An event that describes the successful operation of an application, driver, or service. For example, when a network driver loads successfully, it may be appropriate to log an Information event. Note that it is generally inappropriate for a desktop application to log each time it starts.
Success Audit : An event that records an audited security access attempt that is successful. For example, a user's successful attempt to log on to the system is logged as a Success Audit event.
Failure Audit : An event that records an audited security access attempt that fails. For example, if a user tries to access a network drive and fails, the attempt is logged as a Failure Audit event.

By default Windows NT create 3 Standard Log files where you can log your events.

Application Log : Contains events logged by applications and services. For example, a database application might record a file error. The application developer decides which events to monitor.
System Log : Contains events logged by system components, such as the failure of a driver or other system component to load during startup. The events logged by system components are predetermined.
Security Log : Contains events such as valid and invalid logon attempts, as well as events related to resource use such as creating, opening, or deleting files or other objects. An administrator can turn on auditing to record events in the security log.

Most of times these 3 logs are enough but if you want your own Log then you can create custom log too.

Things to know before you write to EventLog

When you write to EventLog you have to specify Source of Event and EventLog Name (i.e Application, System, Security...), Event type (i.e error,warning, information, audit succees/fail) and some other parameters (i.e message text, username, EventNumber, Category etc).

You can specify your Application name or your company name or something else as a source of event. This source will appear under source column when you view events in NT Event Viewer. By just specifying Eevet source is not enough .... ya there is lot to do before you specify your own event source. Now I will explain you how to create your own event source.

Windows NT stores Registered Event Logs (i.e Application, System, Security...) under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\EventLog registry key

and Registered Event Sources are stored under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\EventLog\{LogName} registry key

Example:

HKEY_LOCAL_MACHINE
   - SYSTEM
     - CurrentControlSet
        - Services
          - EventLog
             - Application
               - AppName
               - AppName
               - AppName
               - .......
               - .......
             + Security
             - System
               - DriverName
               - DriverName
               - DriverName
               - ..........
               - ..........
             - CustomLog
               - AppName
               - AppName
               - AppName
               - .......
               - .......

You cannot use a source name that has already been used as a log name. In addition, source names cannot be hierarchical; that is, you they cannot contain the backslash character (\).

Each Source key can have following values.

CategoryCount : Number of event categories supported. This value is of type REG_DWORD.
CategoryMessageFile : Path for the category message file. A category message file contains language-dependent strings that describe the categories. This value is of type REG_EXPAND_SZ.
EventMessageFile : Path for the event message file. You can list multiple files, separated by semicolons. An event message file contains language-dependent strings that describe the events. This value is of type REG_EXPAND_SZ.
ParameterMessageFile : Path for the parameter message file. A parameter message file contains language-independent strings that are to be inserted into the event description strings. This value is of type REG_EXPAND_SZ.
TypesSupported : Bitmask of supported types. This value is of type REG_DWORD. It can be one or more of the following values:

Understanding MessageFiles

Now fun begins... until now you learned the basic things about EventLog. Now I will explain you what is Message File and how to create a Message File to store Message Defination about various events and categories so Windows NT can map EventId or CategoryId to a description to that ID.

Basically Message Files are compiled resource generally stored in a DLL or Exe. You can create seperate file for each (i.e. Events, Category or Parameter) or you can put all in one file. Message defination file can be speperate than your Application executable of you can mearge this as a resource file. Most of time its useful to mearge Message File as resource in to your Application dll/exe so you dont have to manage multiple files.

Here is the steps to create Message File which we will use in our Article for demo.

Step-By-Step Example (Creating Message File)

- Create .mc file as shown below

MsgFile.mc

;////////////////////////////////////////////////////////////////////////
;// Eventlog categories (if any category defined then always comes first)
;////////////////////////////////////////////////////////////////////////

MessageId=1
Language=English
MyCat1
.

MessageId=2
Language=English
MyCat2
.

MessageId=3
Language=English
MyCat3
.

;////////////////////////////////////////////////////////////////////////
;// Some Event Definations
;////////////////////////////////////////////////////////////////////////

MessageId=1000
Language=English
%1
.

MessageId=1001
Language=English
Drive %1 has only %2 MB free, Please free some disk space
.

MessageId=1002
Language=English
Hello %1 ...How are you
.

MessageId=1003
Language=English
Just Information
.
MessageId=1004
Language=English
Here is your message : %1
.

;////////////////////////////////////////////////////////////////////////
;// Some Parameter Message string
;////////////////////////////////////////////////////////////////////////

MessageId=5000
Language=English
Message number 5000
.

MessageId=5001
Language=English
Message number 5001
.

MessageId=5002
Language=English
Message number 5002
.

- Next step is to Compile MsgFile.mc file (created in previous step) using the following script:

NOTE: Before you run this script make sure that your PATH Environment variable is set to proper path so you dont have to type full path for MC.exe and RC.exe. To set PATH variable on Win2k/XP/2003 right click on "My Computer"->Properties, Click on the Advanced Tab, Click on Environment Variables button, in the bottom list select PATH variable and click edit. Now add paths where RC.exe and MC.exe is located (Paths are seperated by semicolun (;)). On Win 9x/ME you can add PATH in Autoexec.bat file (e.g PATH="c:\Program Files\Microsoft Visual Studio\VB98\Wizards").

MC.exe (Message Compiler) does not come with Visual Basic. If you have VC++ is installed on your system then you can find at \VC98\Bin\MC.exe. If you dont have VC++ installed then you have to find MC.exe from Platform SDK.

RC.exe comes with Visual Basic and generally it is located at \VB98\Wizards\RC.exe. You can create a batch file to run the following script.

CreateResFile.bat

mc MsgFile.mc
rc -r -fo MsgFile.res MsgFile.rc
del MSG00001.bin
del MsgFile.h
del MsgFile.rc

- Run CreateResFile.bat
- After you run CreateResFile.bat one file MsgFile.Res will be created. We will use this file as a resource file in our Visual Basic Application.
- If you dont want to use embedded resource then you have to add the following command in our previous batch file to create DLL file which contains message dfinations.

link /nologo /NOENTRY /subsystem:windows /dll /machine:I386 /out:"MyAppMessages.dll" MsgFile.res

- Now Resource file is ready to use in your Visual Basic Project. In my next article you will learn how to implement CEventLog class.

Next Article : Working with NT EventLog - Part 2 (Implementing CEventLog Class, Creating Event Source)

<< Previous Article | Next Article >>