Handling Event Logs, Part 3

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

This issue, we’ll finish up with our look at integrating the Event Log into an application to store and manage event information. In the first two parts of this series, we examined creating an event source, reporting events, and establishing custom categories for use in filtering.

First, we’ll add the remaining code to the reporting event logic in Part 2.

Once you’re done reporting an event or events to the log, you need to perform some final cleanup as you might expect. Here is what we have so far:

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

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

Note: The call to the function RegisterEventSource in this newsletter was incorrectly named in Part 2 (where I referenced the nonexistent Win32 function RegisterEventLog). If you noticed the error, you get bonus points…

At this point, the final chunk of code is to release the event source when we're done with it:

   if  (!DeregisterEventSource(hEvtLog)) 
   {
      // failed to close the handle to the log..
   }

Okay, that brings our look at reporting events to an end. Next up is reading the event logs existing entries. This might be useful if you want to display a custom event log in your application or scan for events that have a special meaning.

Reading the event log involves a series of straightforward steps: open a logfile on a specific computer, read one or more events from that logfile, and then close the logfile. Let’s look at some code that illustrates these steps:

   HANDLE hEvtLog = OpenEventLog( NULL,"Application");
   if ( hEvtLog )
   {
      const int bufSize = 8192;
      BYTE buffer[bufSize];
      EVENTLOGRECORD *pRec = &buffer;

      DWORD bytesRead=0,minBytesNeeded=0;
      while ( ReadEventLog( hEvtLog, 
EVENTLOG_SEEK_READ | EVENTLOG_FORWARDS_READ,
0,
pRec,
bufSize,
&bytesRead,
&minBytesNeeded ) )
      {
         // move through the "buffer"up to "bytesRead"number of bytes
         while( bytesRead > 0 )
         {
            // get the string description for this entry..
            char str[bufSize];
            strcpy( str,(pRec+pRec->StringOffset) );

            bytesRead -= pRec->Length;

            BYTE* p = (BYTE*)pRec;
            p += pRec->Length;
            pRec = (EVENTLOGRECORD*)p;
         }
      }
   }

   CloseEventLog(hEvtLog);

You’ll notice the meat of the logic revolves around the call to ReadEventLog. As with many functions in the SDK, this one has a large number of parameters, both input and output. The second parameter allows for both reading forward and backward in the log as well as using the third parameter to seek to a specific position. The EVENTLOGRECORD structure is fairly complicated with values for multiple elements in an event record. An important aspect to understand is that the EVENTLOGRECORD functions as a sort of header block in front of the actual data for the record. Be sure to size the initial block of memory passed to ReadEventLog large enough to handle a single record—if not, the function will return zero and GetLastError will return ERROR_INSUFFICIENT_BUFFER. However, ReadEventLog will guarantee that it will return an integral number of event records up to the size of the buffer provided.

Finally, one lesser function for dealing with the event log that you might find useful is NotifyChangeEventLog. This function provides for notification via a Win32 event that a change was made to a specific event log—again, using OpenEventLog to get a handle to the log is needed.

There are a few more event log functions available that may also be useful. I suggest reading through the MSDN Library for more information on these. But at this point, you should have a good understanding of how to add event logging to your application.

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