CTRPP

The CTRPP tool is a pre-processor that parses and validates the manifest for your V2 provider. The tool generates .rc resources with the strings needed by consumers of your provider, and it generates a .h header with code that you use to provide your counter data. You should run the CTRPP tool during the build of your provider. You should use the generated code as a starting point when developing your provider instead of trying to generate this code yourself.

ctrpp -o codeFile -rc rcFile [-legacy] [-MemoryRoutines] [-NotificationCallback] [-prefix prefix] [-ch symFile] [-backcompat] inputFile

Arguments

Option	Description
inputFile	Required: Specifies the name of the .man (XML manifest) file that defines your counters.
-o codeFile	Required: Specifies the name of the .h code file to be generated by CTRPP. This file will contain C/C++ inline helper functions that simplify initializing and uninitializing your provider.
-rc rcFile	Required: Specifies the name of the .rc (resource file) to be generated by CTRPP. This file will contain the provider's string table.
-ch symFile	Specifies the name of the optional .h symbol file to be generated by CTRPP. This file will contain C/C++ symbols for the names and GUIDs of each counterset in the provider.
-prefix prefix	Specifies the prefix to use for the variables and functions defined in the generated header file.
-NotificationCallback	Changes the default signature of the CounterInitialize function to include parameters for specifying the name of ControlCallback, AllocateMemory, and FreeMemory callback functions. This argument has the same effect as including the callback attribute in the provider element.
-migrate outputFile	Instead of generating .h and .rc files, upgrades the inputFile manifest to the latest version and saves it to outputFile. This switch cannot be used with other switches. Usage: CTRPP -migrate NewFile.man OldFile.man
-BackCompat	Deprecated: Support for kernel-mode providers was added in Windows 7. By default, the code generated by CTRPP for kernel-mode providers will be incompatible with earlier versions of Windows (driver will fail to load due to missing Pcw*** APIs). Set -BackCompat to enable compatibility with earlier versions of Windows. The driver will dynamically load the necessary APIs and the generated code will silently disable the provider if the APIs are not available.
-MemoryRoutines	Deprecated: When used with the -Legacy switch, includes templates for memory routines in the generated code. Otherwise, this argument has the same effect as the -NotificationCallback switch.
-Legacy	Deprecated: Generates *.h, *.c, *.rc, and *_r.h files using the Windows Vista code templates (generates PerfAutoInitialize and PerfAutoCleanup instead of CounterInitialize and CounterCleanup). This switch can be used with -MemoryRoutines and -NotificationCallback but cannot be used with any other switches. Do not use the -o or -rc switches with this switch. The generated files will be named based on the name of the manifest and will be written to the directory that contained the manifest. Usage: CTRPP -legacy OldFile.man

Remarks

The CTRPP tool generates a .h code file, an .rc resource file, and optionally generates a .h symbol file.

Using the generated resource file

The CTRPP tool will generate a .rc resource file that contains the localizable strings needed by consumers of the provider's countersets.

Important

The resources from this file must be included into your provider binary and the full path to the provider binary must be registered during the installation of your provider's manifest. Consumers that are unable to locate and load the resources will be unable to use your provider's countersets.

The string resources should be handled as follows:

• The developer edits the provider manifest (.man) file to set the applicationIdentity attribute of the provider to the name of a provider binary (.DLL, .SYS, or .EXE) that will contain the string resources for the provider and will be installed as part of the provider component.
• The CTRPP tool reads the provider manifest and generates an .rc file.
• The RC (resource compiler) tool compiles the data from the CTRPP-generated .rc file to generate a .res file containing the binary resources. This can be done either by directly compiling the CTRPP-generated .rc file OR by compiling another .rc file that includes the CTRPP-generated .rc file via an #include directive.
• The linker embeds the data from the RC-generated .res file into the provider binary.
• During installation, the provider binary is copied onto the user's system and the provider manifest is registered using the lodctr tool. The lodctr tool converts the applicationIdentity attribute of the provider manifest into a full path and records the full path to the provider binary in the registry.
  • If the provider binary is in the same directory as the manifest, use: lodctr.exe /m:"C:\full\manifest\path\manifest.man". lodctr will combine the specified manifest path with the manifest's applicationIdentity attribute to form the full path.
  • Otherwise, use lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path". lodctr will combine the specified binary path with the manifest's applicationIdentity attribute to form the full path.
  • For diagnostic purposes, you can inspect the recorded full path by checking the ApplicationIdentity value of registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>}.
  • If the binary is using MUI for localization, be sure to copy the MUI file along with the binary.
• During counterset collection, the consumer uses the recorded full path to the provider binary to locate and load the necessary strings from the provider binary's resources.

Using the generated code file in a user-mode provider

The CTRPP tool will generate a .h C/C++ code file. If the provider manifest's providerType attribute is set to userMode, the generated code file will contain the following definitions that are helpful in coding a user-mode provider:

• An provider initialization function named prefixCounterInitialize.
• A provider cleanup function named prefixCounterCleanup.
• A global provider variable that stores the provider handle opened by the prefixCounterInitialize function. The variable's name is the value of the symbol attribute of the provider element in the manifest. This variable should be used in calls to PerfCreateInstance, PerfDeleteInstance, and other APIs for controlling your provider's data.
• For each counterset, a global countersetGUID variable with the counterset GUID. The variable's name is the value of the counterSet element's symbol attribute plus the suffix "GUID", e.g. MyCounterSetGUID. This variable should be used in calls to PerfCreateInstance, PerfDeleteInstance, and other APIs for controlling your provider's data.
• For each counter, a counter macro with the counter's id value. The macro's name is the value of the counter element's symbol attribute. This macro should be used in calls to PerfSetCounterRefValue, PerfSetULongLongCounterValue, and other APIs for setting your provider's data.

In the function names, prefix refers to the value of the -prefix command-line parameter. If the -prefix parameter is not used the functions will be named CounterInitialize and CounterCleanup.

Using the generated code file in a kernel-mode provider

The CTRPP tool will generate a .h C/C++ code file. If the provider manifest's providerType attribute is set to kernelMode, the generated code file will contain the following definitions that are helpful in coding a kernel-mode provider's countersets:

• A counterset initialization function named prefixRegisterCounterset. This function fills in a RegInfo structure then invokes PcwRegister, putting the resulting counterset registration handle into the global Counterset variable.
• A counterset cleanup function named prefixUnregisterCounterset. This function invokes PcwUnregister on the counterset registration handle in the global Counterset variable.
• An instance creation function named prefixCreateCounterset. This function fills in an array of PcwData structures then invokes PcwCreateInstance using the counterset registration handle in the global Counterset variable.
• An instance cleanup function named prefixCloseCounterset. This function invokes PcwCloseInstance.
• An instance reporting function named prefixAddCounterset to be used from the counterset callback function. This function fills in an array of PcwData structures then invokes PcwAddInstance.
• Windows SDK 20H1 and later: A RegInfo initialization function named prefixInitRegistrationInformationCounterset for use in advanced scenarios. This function fills in a RegInfo structure. This function can be used in cases where the generated prefixRegisterCounterset does not meet your needs, e.g. when you want to customize the values in the RegInfo structure or when you want to store the returned handle in another variable.

In the function names, prefix refers to the value of the -prefix command-line parameter. If the -prefix parameter is not used the functions will have no prefix.

Note

The generated prefixAddCounterset function is used when you have a counterset callback. The generated prefixCreateCounterset and prefixCloseCounterset functions are used when you do not have a counterset callback.

Using the generated symbol file

If the -ch parameter is specified on the command line, the CTRPP tool will generate a .h symbol file. This file contains the C/C++ symbols for the names and GUIDs of each counterset in the provider. The symbols can be used when writing programs that are hard-coded to consume the data from this counterset using the PerfLib V2 Consumer functions.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]