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

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.

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.

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