Edit

How do you define custom data types?

  • Article

Event Tracing for Windows (ETW) defines several simple and complex types for use in the tracing functions. These types are declared in the Defaultwpp.ini file. However, you can create your own custom data types.

You use a custom data type when you want to declare variables and use meaningful terms--instead of integers--to describe the value of the variables.

For example, the DiskState variable contains the state of the disk. The following are values of DiskState:

DiskOffline = 0
DiskOnline = 1
DiskFailed = 2
DiskStalled = 3

Instead of reading "DiskState=2" in a trace message, and then having to look up the meaning of 2, you can define a custom type called DiskState, to get a trace message that says "DiskState is Failed."

Creating a Custom Data Type

To create a custom data type, complete the following steps:

  1. Create a local configuration file that has the .ini file name extension, such as localwpp.ini. You cannot add a custom type to a header or source file.

  2. Use the TYPEMACRO constant to define the custom data type.

  3. Identify the configuration data in your sources or header file.

  4. Add the -ini parameter to the RUN_WPP macro in your source file.

  5. Use the custom data type in trace messages.

Defining a TYPEMACRO constant

Define a TYPEMACRO constant that has the following format. The values are defined as a list of strings.

TYPEMACRO(Type,{ItemListLong | ItemListShort | ItemListByteShort | ItemListByteLong},(Value1,Value2...));

where:

ItemListShort
Signed 16-bit integer.

ItemListLong
Signed or unsigned 32-bit integer.

ItemSetByteShort
Signed 16-bit bit value.

ItemSetByteLong
Signed or unsigned 32-bit bit value.

For example:

TYPEMACRO(DiskState,ItemListLong(DiskOffline,DiskOnline,DiskFailed,DiskStalled));

Identifying the Configuration Data

If you added the custom data type to a file that has other code, such as a source file or a header file, then use the begin_wpp config and end_wpp statements to identify the configuration data in the file. For example:

// begin_wpp config
    //TYPEMACRO(DiskState,ItemListLong(DiskOffline,DiskOnline,DiskFailed,DiskStalled));
// end_wpp

If you added the custom data type to a local configuration file, then the begin_wpp config and end_wpp statements are not needed.

Add the -ini parameter

When you create a local configuration file for a custom type, you need to add the -ini parameter to the RUN_WPP statement that invokes the WPP preprocessor.

The -ini parameter directs ETW to search for configuration data in configuration files (.ini), in addition to using Defaultwpp.ini. For example:

RUN_WPP -km -ini:localwpp.ini

Important

You must not specify the -km switch in the RUN_WPP directive for user-mode applications or dynamic-link libraries (DLLs).

Using the Custom Data Type

After you have defined a custom data type, you can use it in trace messages. Precede the type name with a percent sign (%) and surround it with exclamation marks (!). For example:

DoTraceMessage(INFO,"Disk State is %!diskstate!",DiskState);

The resulting trace message uses the constant that you defined to represent the value:

DiskState is Offline.