Microsoft KB Archive/166903

INFO: Event Logging Message Source Build and Install Process

Q166903

The information in this article applies to:

Microsoft Win32 Application Programming Interface (API), included with:
- the operating system: Microsoft Windows NT, versions 3.5, 3.51, 4.0

SUMMARY

The LOGGING sample, found in the Win32 Software Development Kit (SDK) under the Q&A sample tree, provides a full example of Event Logging in Microsoft Windows NT. This article gives an overview of the process to create and install a message source for Event Viewer.

MORE INFORMATION

The LOGGING sample that demonstrates Event Logging is found in the Win32 SDK in:

   \mstools\samples\q_a\logging

The logging sample includes a DLL and an EXE. The DLL provides the source for event log messages and the EXE demonstrates reporting events in the log and displaying log messages.

The following is the procedure to create and install a message source:

Use a text editor to create message compiler source (.MC) file. All of the information regarding the layout of a message compiler source file is provided in the MESSAGES.MC file in its comments in the LOGGING sample.
Compile the .MC file using the MC.EXE, message compiler utility. This utility takes the information from the .MC file and creates three output files, .RC, .BIN, and .H files. The .RC file is to be compiled into the message source DLL, or whatever module you choose to provide a message source for Event Viewer. The .RC file creates a single resource, a message table with an ID of 1. The .BIN file is the binary form of the compiled message table data. The .RC file refers to the .BIN file for the source of data to create a message table resource. The .H file is created so that your event reporting application can refer to the event messages by symbolic name.
Compile the message source module. In the LOGGING sample makefile, the resource compiler uses the .RC and .BIN file to create a .RES file. The .RES file is the sole object for the linker to create the MESSAGES.DLL file. Alternatively, if the message table resource is to be bound to an EXE or DLL that contains executable code, the .RES filename is added to the list of other objects during the link process of making the EXE or DLL.

Create a registry key in the EventLog registry. The event log message source is registered in:

      HKEY_LOCAL_MACHINE\ 
         SYSTEM\ 
         CurrentControlSet\ 
         Services\ 
         EventLog\ 
         Application

It is best for an application to programmatically create the registry key for the message source. The application can do this during initialization or during application installation. The LOGGING sample demonstrates how to create the registry key during application initialization.

The following diagram illustrates the build process and the components:

   +------+              +------+
   | .mc  |--> mc.exe -->| .bin |-----+
   |      |              |      | .rc |-----+
   +------+              +------+     | .h  |
                            |  +------+     |
                            |    |   +------+
                            |   /       |
                            |  /         \ 
       +------+             v v           v
       | .res |<--------- rc.exe        your app source
       |      |
       +------+
          |                      +------+
          +-----> link.exe ----> | .dll |
                                 |      |
                                 +------+

It is up to you to include the .H file in your application that posts events into the event log with ReportEvent. The .DLL is the module that Event Viewer loads to associate strings with the event IDs it reads from the event log.

Additional query words: events evtlog eventlog logging

Keywords : kbprogramming kbEventLog kbKernBase kbGrpDSKernBase
Issue type : kbinfo
Technology : kbAudDeveloper kbWin32sSearch kbWin32API