The DoTraceMessage macro logs a trace message if a specified trace flag is enabled.
void DoTraceMessage( TraceFlagName, Message, [ VariableList ] );
Identifies a trace flag name. This name is specified in the definition of the WPP_CONTROL_GUIDS macro that is made by the kernel-mode driver or user-mode application.
Specifies a string constant that defines the format of the trace message. The string is similar to the printf format string and usually includes literal text interspersed with standard printf format specifications, such as %d and %s. WPP also supports some special formats, such as %!NTSTATUS! and %!HRESULT!, that display string equivalents of kernel-mode status values and user-mode HRESULT values, respectively. For more information about WPP defined format specification strings, see What are the WPP extended format specification strings? For information about the printf type fields, see Format Specification Fields: printf and wprintf Functions.
Specifies a comma-delimited list of variables whose values are added to the message string according to the format specified by Message.
The WPP preprocessor treats the message information in each DoTraceMessage statement as a unique message, and does the following:
- Creates a compiler directive that adds message definition information to the driver's program database (PDB) symbol file. This information includes the GUID of the trace provider and the information needed to format the provider's trace messages.
For example, TraceView can extract the trace message formatting information directly from the PDB file or from a trace message format file (.tmf), known as a TMF file. TraceView and Tracepdb can also extract the formatting data from the PDB file and place it in a separate TMF file for use by other tracing tools, such as Tracefmt.
DoTraceMessage expands, logically, to the following, for kernel-mode drivers:
If (specified message filters are enabled) call WmiTraceMessage ;
DoTraceMessage expands, logically, to the following, for user-mode applications:
If (specified message filters are enabled) call TraceMessage ;
The WPP preprocessor automatically determines the type of variables such as CHAR, SHORT, LONG, *CHAR, and so on. The WPP utilities also handle other built-in variable types that you can explicitly specify in a message definition. You specify these variable types using the %!DataTypeName! notation supported by the FormatMessage function. Two examples are described in the following table.
|Format string||Data Type||Internal Conversion|
Symbolic name string
For more information about other supported built-invariable types, see What are the WPP extended format specification strings?
For an example of making DoTraceMessage calls, see the Tracedrv sample.
Instead of using the DoTraceMessage macro, a kernel-mode driver can log trace messages by directly calling WmiTraceMessage. Similarly, instead of using the DoTraceMessage macro, a user-mode applications can log trace messages by directly calling TraceMessage.
Note If WmiTraceMessage or TraceMessage is called directly, the consumer of trace messages cannot use Tracefmt to format the message information in a human-readable form. This is because, the WPP preprocessor was not started, and annotations that describe the messages format were not inserted in the PDB symbol file that was generated during the build process,
However, the consumer can still use Tracelog to control software tracing.
DoTraceMessage can be called at any IRQL and runs at the IRQL of the caller. However, when the call is at IRQL>DISPATCH_LEVEL and existing trace session buffers are full, the trace messages are lost, because new buffers cannot be allocated at IRQL>DISPATCH_LEVEL.