Figure 13.1 Event Viewer in action
Message Files
When you log an event, you pass an Event Id, a number specifying the event that you are reporting. You must include a message resource in your driver if you want the event viewer to display the appropriate description.
The Wdm3Msg.mc message file for the Wdm3 driver is shown in Listing 13.1. The MessageIdTypedef, SeverityNames, and FacilityNames sections are fairly standard. A facility identifies the type of driver. Most driver writers use the spare facility number of 0x7 for the Wdm3 facility. Microsoft defined facility numbers are defined in NTSTATUS.H.
The following blocks of lines define one message at a time. The contents of each line are self-explanatory. The actual event message is on one or more lines, ending with a line that contains just a period. The following escape codes have special meaning in the message text: %b is a space, %t is a tab, %v is a carriage return, and %n is a linefeed. In addition, %1 to %99 are where driver-supplied strings are inserted. Actually, %1 is always the driver name, so the driver strings start with 11.
Listing 13.1 Wdm3Msg.mc message file
MessageIdTypedef = NTSTATUS
SeverityNames = (
Success = 0x0:STATUS_SEVERITY_SUCCESS
Informational = 0x1:STATUS_SEVERITY_INFORMATIONAL
Warning = 0x2:STATUS_SEVERITY_WARNING
Error = 0x3:STATUS_SEVERITY_ERROR
)
FacilityNames = (
System = 0x0
Wdm3 = 0x7:FACILITY_WDM3_ERROR_CODE
)
MessageId=0x0001
Facility=Wdm3
Severity=Informational
SymbolicName=WDM3_MSG_LOGGING_STARTED
Language=English
Event logging enabled for Wdm3 Driver.
.
MessageId=+1
Facility=Wdm3
Severity=Informational
SymbolicName=WDM3_MESSAGE
Language=English
Message: %2.
.
The mc command is used to compile the message definition file. It produces three or more output files. In this case, these are the Wdm3Msg.rc resource script, the Wdm3Msg.h header file, and the MSG00001.BIN message data file. Further message files are produced if you support more than one language. The Wdm3Msg.rc resource script contains just a reference to the MSG00001.BIN message data file (or files), as follows.
LANGUAGE 0x9,0x1
1 11 MSG00001.bin
The Wdm3Msg.h header file contains the message symbolic names defined in a form that can be used by the driver code, as shown in Listing 13.2. The message ID, severity, and facility code have been combined, with the 'customer' bit set to make a suitable NTSTATUS value. The main Wdm3 header, Wdm3.h, now also includes Wdm3Msg.h.
Listing 13.2 Wdm3Msg.h file
// MessageId: WDM3_MSG_LOGGING_STARTED
//
// MessageText:
//
// Event logging enabled for Wdm3 Driver.
//
#define WDM3_MSG_LOGGING_STARTED ((NTSTATUS)0x60070001L)
//
// MessageId: WDM3_MESSAGE
//
// MessageText:
//
// Message: %2.
//
#define WDM3_MESSAGE ((NTSTATUS)0x60070002L)
The message file must be compiled before the main driver code is built. The NTTARGETFILE0 macro in the SOURCES file is used to specify any prebuild steps.
NTTARGETFILE0=prebuiId
As described in Chapter 4, this invokes nmake on the makefile.inc makefile before the main compile. The prebuild step compiles the WMI MOF file and the event message definition file, as shown in Listing 13.3. The mc command is run, if necessary, using the –c option to set the 'customer' bit and the –v option for verbose output.
Listing 13.3 New makefile.inc
prebuild: Wdm3Msg.h Wdm3.bmf
Wdm3.bmf: Wdm3.mof
mofcomp –B:Wdm3.bmf –WMI Wdm3.mof
Wdm3Msg.rc Wdm3Msg.h: Wdm3Msg.mc
mc –v –c Wdm3Msg.mc
PostBuildSteps: $(TARGET)
!if '$(DDKBUILDENV)'=='free'
rebase –B 0x10000 –X . $(TARGET)
!endif
copy $(TARGET) $(WINDIR)system32drivers
The final change to the build process is to make the main resource file, Wdm3.rc, include the message resource script, Wdm3Msg.rc. In Visual C++, select the
#include 'Wdm3Msg.rc'
In Windows 2000, I found that building the driver from a changed message definition file initially reported an error but then went on to compile successfully.
Registering as an Event Source
