Handling Event Logs, Part 2

[This is part 2 of a series on using the Event Log]

In the last newsletter, we looked at an initial set of steps to provide for interacting with the Windows EventLog. We configured a message file that would manage the types of messages we would submit to the EventLog, and added an event source to the registry. This time, we’ll finish up and look at reporting an event and querying the EventLog.

An application using the EventLog to store messages of various types will likely have numerous places in the source code where these messages are generated. Fortunately, the EventLog is fairly easy to interact with to submit or report these messages.

The first step is to register an event source. An event source refers to the name of the application that wishes to log an event. The most common name used is the name of the application itself, but can be any value that is relevant to the application. Let’s look at some code:

	HANDLE hEvtLog = RegisterEventSource( NULL,"MyCoolApp");
	if (hEvtLog )
	{
		// we have a handle to a valid log..
	}

You might be wondering which event log will be returned from this call. Looking at the code from the last issue we see the following:

    HKEY key = 0;	<br>    if (!RegCreateKey(HKEY_LOCAL_MACHINE, <br>            "SYSTEM\\CurrentControlSet\\Services\ <br>            \\EventLog\\Application\\MyCoolApp", &key)) <br>    {<br>	          // rest of code not shown for clarity..<br>    }

Notice that the key is created under the Application type event log. Since the key is under the Application key in the registry, that tells us that the event log returned from the RegisterEventSource call earlier will be the Application event log. Although you could create and manage an alternate event log than Application, it is likely that most developers will stick to the default Application log for simplicity.

Now that we’ve gotten a valid handle to an event log, we can begin sending messages to it. For this, we call the ReportEvent API:

	if ( !ReportEvent( hEvtLog,
                    EVENTLOG_WARNING_TYPE,
			              0,
                    MSG_TRACE_ERROR,
			             NULL,
			             1,
			             0,
			             "Warning:  something unusual happened..
			              NULL ) )
           {
		            // unable to report event..
           }

The first parameter to ReportEvent is the handle to the event log retrieved from the call to RegisterEventSource.

The second parameter is the type of event being logged. There are a series of defined values such as Success, Error, Information, Warning, and the like, that are enumerated (see MSDN for more information).

The third parameter is an optional event category. A category can be used to provide for easier filtering in the event log when using the event viewer application that comes with Windows. The categories are specified in a message file by themselves or in the message file containing other types of messages. You would also update the CategoryCount key for the event source to contain the total number of categories that are assumed to begin with the value 1. Finally, you'd update the CategoryMessageFile key to point to the message file containing the categories (this last item is not mentioned in MSDN, but it is required). Let's look at how the message file we created last issue would appear if we added message categories (note that the categories must appear at the top of the message file if combined with other kinds of messages):

SeverityNames=(Success=0x0:STATUS_SEVERITY_SUCCESS
               Informational=0x1:STATUS_SEVERITY_INFORMATIONAL
               Warning=0x2:STATUS_SEVERITY_WARNING
               Error=0x3:STATUS_SEVERITY_ERROR
              )

FacilityNames=(System=0x0:FACILITY_SYSTEM
               Runtime=0x2:FACILITY_RUNTIME
               Stubs=0x3:FACILITY_STUBS
               Io=0x4:FACILITY_IO_ERROR_CODE
              )

LanguageNames=(English=0x409:MSG00409)

MessageId=0x1
Severity=Success
SymbolicName=PRIMARY
Language=English
Primary
.
MessageId=0x2
Severity=Success
SymbolicName=SECONDARY
Language=English
Secondary
.
MessageId=0x3
Severity=Error
Facility=Runtime
SymbolicName=MSG_TRACE_ERROR
Language=English
%1
.
MessageId=0x4
Severity=Warning
Facility=Runtime
SymbolicName=MSG_TRACE_ALERT
Language=English
%1
.
MessageId=0x5
Severity=Informational
Facility=Runtime
SymbolicName=MSG_TRACE_INFO
Language=English
%1
.
MessageId=0x6
Severity=Informational
Facility=Runtime
SymbolicName=MSG_TRACE_DEBUG
Language=English
%1
.

And here is a screen shot of my copy of Event Viewer showing my event source and the custom categories:

Next time, we'll finish up our look at using the event log to track events from an application.

Correction Note: The call to the function RegisterEventSource was previously labeled as a nonexistent Win32 function, RegisterEventLog. Sorry for any confusion this may have caused.

Mark M. Baker is the Chief of Research & Development at BNA Software located in Washington, D.C.
Do you have a Windows development question? Send it to [email protected].