Книга: Writing Windows WDM Device Drivers

Message Files

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 View+Resource Includes… menu and add the following line to the "Read-only symbol directives" box.

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

Оглавление книги