DoTraceMessage

  • Article

The DoTraceMessage macro logs a trace message if a specified trace flag is enabled.

void
  DoTraceMessage(
     TraceFlagName,
     Message,
     [ VariableList ]
);

Parameters

  • TraceFlagName
    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.

  • Message
    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.

  • VariableList
    Specifies a comma-delimited list of variables whose values are added to the message string according to the format specified by Message.

Headers

Defined in a source file's trace message header file. The WPP preprocessor generates the header file and saves in the same directory as the source file.

Comments

The WPP preprocessor treats the message information in each DoTraceMessage statement as a unique message, and does the following:

  • Defines macros in the driver's trace message header file which, ultimately, result in WmiTraceMessage calls (for kernel-mode drivers) or TraceMessage.calls (for user-mode applications).

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

    Trace consumers use this information to identify the trace provider and format its 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 ;

Note  You can create your own version of DoTraceMessage macro and you can supply additional conditions for trace messages. See Can I customize DoTraceMessage? for more information.

 

A trace consumer, such as TraceView or Tracelog, can enable a trace flag by setting its corresponding bit.

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

%!IPAddr!

ULONG

"Xxx.Xxx.Xxx.Xxx" string

%!STATUS!

NTSTATUS

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.

Examples

   
    DoTraceMessage(FLAG_ONE, "IOCTL = %d", ioctlCount);

    
    DoTraceMessage(FLAG_ONE,  "Hello, %d %s", i, "Hi" );

    
   DoTraceMessage(FLAG_TWO, L"Initializing Filter");

See also

Can I customize DoTraceMessage?

 

 

Send comments about this topic to Microsoft