CTRPP

De CTRPP tool is een pre-processor die het manifest voor uw V2 provider parseert en valideert. De tool genereert .rc bronnen met de strings die consumenten van uw provider nodig hebben, en het genereert een .h header met code die u gebruikt om uw tellergegevens te verstrekken. U moet de CTRPP-tool uitvoeren tijdens de bouw van uw provider. U moet de gegenereerde code als uitgangspunt gebruiken bij het ontwikkelen van uw provider in plaats van te proberen deze code zelf te genereren.

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

Argumenten

Optie	Beschrijving
inputBestand	Vereist: Hiermee geeft u de naam op van het .man bestand (XML-manifest) dat uw tellers definieert.
-ocodeBestand	Vereist: Geeft de naam op van het .h codebestand dat door CTRPP moet worden gegenereerd. Dit bestand bevat C/C++ inline helperfuncties die het initialiseren en ongedaan maken van uw provider vereenvoudigen.
-rcrcBestand	Vereist: Hiermee geeft u de naam op van het .rc (bronbestand) dat door CTRPP moet worden gegenereerd. Dit bestand bevat de tekenreekstabel van de provider.
-chsymBestand	Hiermee geeft u de naam op van het optionele .h symboolbestand dat door CTRPP moet worden gegenereerd. Dit bestand bevat C/C++-symbolen voor de namen en GUID's van elke tegenset in de provider.
-voorvoegselvoorvoegsel	Hiermee geeft u het voorvoegsel op dat moet worden gebruikt voor de variabelen en functies die zijn gedefinieerd in het gegenereerde headerbestand.
-MeldingTerugbellen	Wijzigt de standaardhandtekening van de functie CounterInitialize om parameters op te nemen voor het opgeven van de naam van de callbackfuncties ControlCallback, AllocateMemory en FreeMemory . Dit argument heeft hetzelfde effect als het opnemen van het callback kenmerk in het provider-element .
-uitvoer migreren	In plaats van het genereren .h van bestanden .rc , werkt het inputFile-manifest bij naar de nieuwste versie en slaat het op in outputFile. Deze schakelaar kan niet worden gebruikt met andere schakelaars. Gebruik: CTRPP -migrate NewFile.man OldFile.man
-BackCompat	Verouderd: Ondersteuning voor kernel-mode providers is toegevoegd in Windows 7. Standaard is de code die door CTRPP wordt gegenereerd voor kernelmodusproviders niet compatibel met eerdere versies van Windows (stuurprogramma kan niet worden geladen vanwege ontbrekende Pcw*** API's). Instellen -BackCompat om compatibiliteit met eerdere versies van Windows mogelijk te maken. Het stuurprogramma laadt dynamisch de benodigde API's en de gegenereerde code schakelt de provider op de achtergrond uit als de API's niet beschikbaar zijn.
-Geheugen Routines	Verouderd: Bij gebruik met de switch, bevat het -Legacy sjablonen voor geheugenroutines in de gegenereerde code. Voor het overige heeft dit argument hetzelfde effect als de -NotificationCallback switch.
-Nalatenschap	Verouderd: Genereert *.h, *.c, *.rc, en *_r.h bestanden met behulp van de Windows Vista-codesjablonen (genereert PerfAutoInitialize en PerfAutoCleanup in plaats van CounterInitialize en CounterCleanup). Deze switch kan worden gebruikt met -MemoryRoutines en -NotificationCallback , maar kan niet worden gebruikt met andere switches. Gebruik de -o of -rc schakelaars niet met deze schakelaar. De gegenereerde bestanden krijgen een naam op basis van de naam van het manifest en worden geschreven naar de map die het manifest bevatte. Gebruik: CTRPP -legacy OldFile.man

Opmerkingen

De CTRPP-tool genereert een .h codebestand, een .rc bronbestand en optioneel een .h symboolbestand.

Het gegenereerde bronbestand gebruiken

De CTRPP-tool genereert een .rc bronbestand dat de lokaliseerbare strings bevat die consumenten van de tegensets van de provider nodig hebben.

Belangrijk

De bronnen uit dit bestand moeten worden opgenomen in het binaire bestand van uw provider en het volledige pad naar het binaire bestand van de provider moet worden geregistreerd tijdens de installatie van het manifest van uw provider. Consumenten die de bronnen niet kunnen vinden en laden, kunnen de tellers van uw provider niet gebruiken.

De tekenreeksbronnen moeten als volgt worden behandeld:

• De ontwikkelaar bewerkt het bestand met het providermanifest (.man) om het applicationIdentity kenmerk van de provider in te stellen op de naam van een binaire provider (.DLL, .SYS of .EXE) die de tekenreeksbronnen voor de provider bevat en die wordt geïnstalleerd als onderdeel van het provideronderdeel.
• De CTRPP-tool leest het manifest van de provider en genereert een .rc bestand.
• De RC-tool (resource compiler) compileert de gegevens uit het door CTRPP gegenereerde .rc bestand om een .res bestand te genereren dat de binaire bronnen bevat. Dit kan worden gedaan door het door CTRPP gegenereerde .rc bestand rechtstreeks te compileren OF door via een #include instructie een ander .rc bestand te compileren dat het door CTRPP gegenereerde .rc bestand bevat.
• De linker sluit de gegevens uit het door RC gegenereerde .res bestand in het binaire bestand van de provider in.
• Tijdens de installatie wordt het binaire bestand van de provider gekopieerd naar het systeem van de gebruiker en wordt het providermanifest geregistreerd met behulp van de lodctr-tool. De lodctr-tool zet het applicationIdentity kenmerk van het providermanifest om in een volledig pad en registreert het volledige pad naar het binaire bestand van de provider in het register.
  • Als het binaire bestand van de provider zich in dezelfde directory bevindt als het manifest, gebruikt u: lodctr.exe /m:"C:\full\manifest\path\manifest.man". LoCtr combineert het opgegeven manifestpad met het kenmerk van applicationIdentity het manifest om het volledige pad te vormen.
  • Gebruik anders lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path". LoWcTR combineert het opgegeven binaire pad met het attribuut van applicationIdentity het manifest om het volledige pad te vormen.
  • Voor diagnostische doeleinden kunt u het opgenomen volledige pad inspecteren door de waarde van de ApplicationIdentity registersleutel HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>}te controleren.
  • Als het binaire bestand MUI gebruikt voor lokalisatie, zorg er dan voor dat u het MUI-bestand samen met het binaire bestand kopieert.
• Tijdens het verzamelen van tegensets gebruikt de consument het opgenomen volledige pad naar het binaire bestand van de provider om de benodigde tekenreeksen te lokaliseren en te laden uit de binaire bronnen van de provider.

Het gegenereerde codebestand gebruiken in een provider in de gebruikersmodus

De CTRPP-tool genereert een .h C/C++-codebestand. Als het kenmerk van providerType het providermanifest is ingesteld op userMode, bevat het gegenereerde codebestand de volgende definities die nuttig zijn bij het coderen van een provider in de gebruikersmodus:

• n provider initialisatiefunctie met de naam voorvoegselCounterInitialize.
• Een functie voor het opschonen van de provider met het voorvoegselCounterCleanup.
• Een globale providervariabele die de providerhandle opslaat die wordt geopend door het voorvoegselCounterInitialize-functie . De naam van de variabele is de waarde van het symbol kenmerk van het provider element in het manifest. Deze variabele moet worden gebruikt in aanroepen naar PerfCreateInstance, PerfDeleteInstanceen andere API's voor het beheren van de gegevens van uw provider.
• Voor elke tegenset: een globale GUID-variabele voor de tellerset met de GUID voor de tellerset. De naam van de variabele is de waarde van het kenmerk van symbol het counterSet element plus het achtervoegsel "GUID", bijvoorbeeld MyCounterSetGUID. Deze variabele moet worden gebruikt in aanroepen naar PerfCreateInstance, PerfDeleteInstanceen andere API's voor het beheren van de gegevens van uw provider.
• Voor elke teller een tellermacro met de waarde van id de teller. De naam van de macro is de waarde van het kenmerk van symbol het counter element. Deze macro moet worden gebruikt in aanroepen naar PerfSetCounterRefValue, PerfSetULongLongCounterValueen andere API's voor het instellen van de gegevens van uw provider.

In de functienamen verwijst het voorvoegsel naar de waarde van de -prefix opdrachtregelparameter. Als de -prefix parameter niet wordt gebruikt, krijgen de functies een naam CounterInitialize en CounterCleanup.

Het gegenereerde codebestand gebruiken in een kernelmodusprovider

De CTRPP-tool genereert een .h C/C++-codebestand. Als het kenmerk van het manifest van providerType de provider is ingesteld op kernelMode, bevat het gegenereerde codebestand de volgende definities die nuttig zijn bij het coderen van de tellersets van een kernelmodusprovider:

• Een initialisatiefunctie voor de tellerset met de naam voorvoegselRegister Counterset. Deze functie vult een RegInfo-structuur in en roept vervolgens PcwRegister aan, waarbij de resulterende registratiegreep voor tegensets in de globale variabele Tellerset wordt geplaatst.
• Een functie voor het opschonen van tellersets met de naam voorvoegselTellerset onregistreren ongedaan. Deze functie roept PcwUnregister op de registratiegreep van de tellerset aan in de globale variabele Tellerset .
• Een functie voor het maken van exemplaren met de naam voorvoegselTellerset maken. Deze functie vult een matrix van PcwData-structuren in en roept vervolgens PcwCreateInstance aan met behulp van de registratiegreep van de tellerset in de globale variabele Tellerset .
• Een functie voor het opschonen van exemplaren met de naam voorvoegselTegenset sluiten. Deze functie roept PcwCloseInstance aan.
• Een exemplaarrapportagefunctie met de naam voorvoegselTellerset toevoegen die moet worden gebruikt vanuit de tegenset-callbackfunctie. Deze functie vult een array van PcwData-structuren in en roept vervolgens PcwAddInstance aan.
• Windows SDK 20H1 en hoger: Een RegInfo-initialisatiefunctie met de naam voorvoegselInitRegistrationInformationCounterset voor gebruik in geavanceerde scenario's. Deze functie vult een RegInfo structuur in. Deze functie kan worden gebruikt in gevallen waarin het gegenereerde voorvoegselRegisterCounterset niet aan uw behoeften voldoet, bijvoorbeeld wanneer u de waarden in de RegInfo-structuur wilt aanpassen of wanneer u de geretourneerde handle in een andere variabele wilt opslaan.

In de functienamen verwijst het voorvoegsel naar de waarde van de -prefix opdrachtregelparameter. Als de -prefix parameter niet wordt gebruikt, hebben de functies geen voorvoegsel.

Opmerking

De gegenereerde functieTellerset toevoegen wordt gebruikt wanneer u een tegenset-callback hebt. Het gegenereerde voorvoegselTellerset maken en VoorvoegselTellerset sluiten worden gebruikt wanneer u geen tegenset-callback hebt.

Het gegenereerde symboolbestand gebruiken

Als de parameter -ch op de opdrachtregel is opgegeven, genereert de CTRPP-tool een .h symboolbestand. Dit bestand bevat de C/C++-symbolen voor de namen en GUID's van elke tegenset in de provider. De symbolen kunnen worden gebruikt bij het schrijven van programma's die hard gecodeerd zijn om de gegevens van deze teller te consumeren met behulp van de PerfLib V2 Consumer-functies.

Behoeften

Voorwaarde	Waarde
Minimaal ondersteunde client	Windows Vista [alleen desktop-apps]
Minimaal ondersteunde server	Windows Server 2008 [alleen desktop-apps]