Nástroj CTRPP

Nástroj CTRPP je předprocesor, který analyzuje a ověřuje manifest pro vašeho poskytovatele V2. Nástroj generuje .rc prostředky s řetězci potřebnými pro spotřebitele vašeho poskytovatele a generuje hlavičku .h s kódem, který používáte k poskytnutí dat čítače. Nástroj CTRPP byste měli spustit během sestavování vašeho poskytovatele. Vygenerovaný kód byste měli použít jako výchozí bod při vývoji poskytovatele místo toho, abyste se pokoušeli tento kód vygenerovat sami.

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

Argumenty

Možnost	Popis
Soubor vstupu	Požadovaný: Určuje název .man souboru (XML manifest), který definuje čítače.
-okódový soubor	Požadovaný: Určuje název .h souboru kódu, který má být generován pomocí CTRPP. Tento soubor bude obsahovat vložené pomocné funkce jazyka C/C++, které zjednodušují inicializaci a zrušení inicializace poskytovatele.
-rcrcSoubor	Požadovaný: Určuje název .rc (zdrojového souboru), který má být generován pomocí CTRPP. Tento soubor bude obsahovat tabulku řetězců poskytovatele.
-chsymFile	Určuje název volitelného .h souboru symbolů, který má být generován pomocí CTRPP. Tento soubor bude obsahovat symboly C/C++ pro názvy a identifikátory GUID každé sady čítačů ve poskytovateli.
-prefixprefix prefix	Určuje předponu, která se má použít pro proměnné a funkce definované ve vygenerovaném souboru hlaviček.
-Zpětné volání oznámení	Změní výchozí signaturu funkce CounterInitialize tak, aby zahrnovala parametry pro určení názvu funkcí zpětného volání ControlCallback, AllocateMemory a FreeMemory . Tento argument má stejný účinek jako zahrnutí atributu callback do elementu provider .
-migrovatvýstupní soubor	Namísto generování .h souborů a .rc upgraduje manifest inputFile na nejnovější verzi a uloží jej do outputFile. Tento přepínač nelze použít s jinými spínači. Použití: CTRPP -migrate NewFile.man OldFile.man
-Zpětný přehled	Zavrhovaný: V systému Windows 7 byla přidána podpora pro poskytovatele režimu jádra. Ve výchozím nastavení bude kód generovaný protokolem CTRPP pro poskytovatele režimu jádra nekompatibilní s dřívějšími verzemi systému Windows (ovladač se nepodaří načíst z důvodu chybějících Pcw*** rozhraní API). Nastavte -BackCompat tak, aby byla povolena kompatibilita se staršími verzemi systému Windows. Ovladač dynamicky načte potřebná rozhraní API a vygenerovaný kód tiše deaktivuje poskytovatele, pokud rozhraní API nejsou k dispozici.
-Paměťové rutiny	Zavrhovaný: Při použití s přepínačem -Legacy obsahuje do vygenerovaného kódu šablony pro paměťové rutiny. V opačném případě má tento argument stejný účinek jako přepínač -NotificationCallback .
-Dědictví	Zavrhovaný: Generuje *.hsoubory , *.c, *.rca *_r.h pomocí šablon kódu systému Windows Vista (generuje PerfAutoInitialize a PerfAutoCleanup namísto CounterInitialize a CounterCleanup). Tento přepínač lze použít s -MemoryRoutines a -NotificationCallback , ale nelze jej použít s žádnými jinými přepínači. S tímto přepínačem nepoužívejte přepínače -o nebo -rc . Vygenerované soubory budou pojmenovány na základě názvu manifestu a budou zapsány do adresáře, který obsahoval manifest. Použití: CTRPP -legacy OldFile.man

Poznámky

Nástroj CTRPP vygeneruje .h soubor kódu, .rc soubor prostředků a volitelně vygeneruje soubor symbolů .h .

Použití vygenerovaného souboru prostředků

Nástroj CTRPP vygeneruje zdrojový .rc soubor, který obsahuje lokalizovatelné řetězce, které potřebují uživatelé protisad poskytovatele.

Důležité

Prostředky z tohoto souboru musí být zahrnuty do binárního souboru vašeho poskytovatele a úplná cesta k binárnímu souboru poskytovatele musí být zaregistrována během instalace manifestu vašeho poskytovatele. Příjemci, kteří nejsou schopni najít a načíst zdroje, nebudou moci používat protisady vašeho poskytovatele.

S prostředky řetězce by se mělo zacházet následovně:

• Vývojář upraví soubor manifestu (.man) zprostředkovatele tak, aby nastavil applicationIdentity atribut zprostředkovatele na název binárního souboru poskytovatele (.DLL, .SYS nebo .EXE), který bude obsahovat řetězcové prostředky pro poskytovatele a bude nainstalován jako součást komponenty poskytovatele.
• Nástroj CTRPP načte manifest poskytovatele a vygeneruje .rc soubor.
• Nástroj RC (kompilátor prostředků) zkompiluje data ze souboru generovaného .rc CTRPP a vygeneruje .res soubor obsahující binární prostředky. To lze provést buď přímou kompilací souboru vygenerovaného .rc CTRPP, NEBO kompilací jiného .rc souboru, který obsahuje soubor vygenerovaný .rc CTRPP pomocí #include direktivy.
• Linker vloží data ze souboru generovaného .res RC do binárního souboru poskytovatele.
• Během instalace se binární soubor zprostředkovatele zkopíruje do systému uživatele a manifest poskytovatele se zaregistruje pomocí nástroje lodctr. Nástroj lodctr převede applicationIdentity atribut manifestu zprostředkovatele na úplnou cestu a zaznamená úplnou cestu k binárnímu souboru poskytovatele do registru.
  • Pokud je binární soubor zprostředkovatele ve stejném adresáři jako manifest, použijte: lodctr.exe /m:"C:\full\manifest\path\manifest.man". LODCTR zkombinuje zadanou cestu manifestu s atributem applicationIdentity manifestu a vytvoří úplnou cestu.
  • V opačném případě použijte lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path". LODCTR zkombinuje zadanou binární cestu s atributem applicationIdentity manifestu a vytvoří úplnou cestu.
  • Pro diagnostické účely můžete zaznamenanou úplnou cestu zkontrolovat kontrolou ApplicationIdentity hodnoty klíče HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>}registru .
  • Pokud binární soubor používá k lokalizaci soubor MUI, nezapomeňte zkopírovat soubor MUI spolu s binárním souborem.
• Během shromažďování protisady příjemce používá zaznamenanou úplnou cestu k binárnímu souboru poskytovatele k vyhledání a načtení potřebných řetězců z prostředků binárního souboru poskytovatele.

Použití vygenerovaného souboru kódu ve zprostředkovateli uživatelského režimu

Nástroj CTRPP vygeneruje .h soubor kódu C/C++. Pokud je atribut manifestu providerType poskytovatele nastaven na , userModevygenerovaný soubor kódu bude obsahovat následující definice, které jsou užitečné při kódování poskytovatele uživatelského režimu:

• n inicializační funkce poskytovatele s názvem prefixCounterInitialize.
• Funkce vyčištění poskytovatele s názvem prefixCounterCleanup.
• Globální proměnná poskytovatele , která ukládá popisovač zprostředkovatele otevřený funkcí předponyCounterInitialize . Název proměnné je hodnota atributu symbol elementu provider v manifestu. Tato proměnná by měla být použita ve voláních rozhraní PerfDeleteInstanceAPI a PerfCreateInstancedalších rozhraní API pro řízení dat vašeho poskytovatele.
• Pro každou sadu čítačů je k dispozici globální proměnná GUID sady čítačů s identifikátorem GUID sady čítačů. Název proměnné je hodnota atributu counterSetsymbol elementu plus přípona "GUID", např. MyCounterSetGUID. Tato proměnná by měla být použita ve voláních rozhraní PerfDeleteInstanceAPI a PerfCreateInstancedalších rozhraní API pro řízení dat vašeho poskytovatele.
• Pro každý čítač makro čítače s hodnotou čítače id . Název makra je hodnota atributu countersymbol prvku. Toto makro by mělo být použito ve voláních rozhraní PerfSetULongLongCounterValueAPI pro PerfSetCounterRefValuenastavení dat vašeho poskytovatele.

V názvech funkcí odkazuje předpona na hodnotu parametru příkazového řádku -prefix . Pokud parametr -prefix není použit, funkce budou pojmenovány CounterInitialize a CounterCleanup.

Použití vygenerovaného souboru kódu ve zprostředkovateli režimu jádra

Nástroj CTRPP vygeneruje .h soubor kódu C/C++. Pokud je atribut manifestu providerType poskytovatele nastaven na , kernelModevygenerovaný soubor kódu bude obsahovat následující definice, které jsou užitečné při kódování protisad poskytovatele v režimu jádra:

• Inicializační funkce countersetu pojmenovaná prefixRegisterCounterset. Tato funkce vyplní strukturu RegInfo a poté vyvolá PcwRegister, čímž umístí výsledný popisovač registrace countersetu do globální proměnné Counterset .
• Funkce vyčištění countersetu s názvem prefixUnregisterCounterset. Tato funkce vyvolá PcwUnregister na popisovači registrace protisady v globální proměnné Counterset .
• Funkce pro vytváření instance s názvem prefixCreate Counterset. Tato funkce vyplní pole struktur PcwData a poté vyvolá PcwCreateInstance pomocí popisovače registrace countersetu v globální proměnné Counterset .
• Funkce vyčištění instance s názvem prefixClose Counterset. Tato funkce vyvolá PcwCloseInstance.
• Funkce hlášení instancí s názvem prefixAddCounterset , která se má použít z funkce zpětného volání countersetu. Tato funkce vyplní pole struktur PcwData a poté vyvolá PcwAddInstance.
• Windows SDK 20H1 a novější: Inicializační funkce RegInfo s názvem prefixInitRegistrationInformationCounterset pro použití v pokročilých scénářích. Tato funkce vyplní strukturu RegInfo . Tuto funkci lze použít v případech, kdy vygenerovaný prefixRegisterCounterset nevyhovuje vašim potřebám, např. když chcete upravit hodnoty ve struktuře RegInfo nebo když chcete vrácený handle uložit do jiné proměnné.

V názvech funkcí odkazuje předpona na hodnotu parametru příkazového řádku -prefix . Pokud parametr -prefix není použit, funkce nebudou mít žádnou předponu.

Poznámka:

Funkce vygenerované předponyAddCounterset se používá, když máte zpětné volání countersetu. Funkce vygenerované předponyCreateCounterset a prefixClose Counterset se používají v případě, že nemáte zpětné volání countersetu.

Použití vygenerovaného souboru symbolů

Pokud je na příkazovém řádku zadán parametr -ch , nástroj CTRPP vygeneruje soubor symbolů .h . Tento soubor obsahuje symboly C/C++ pro názvy a identifikátory GUID každé sady čítačů ve zprostředkovateli. Symboly lze použít při psaní programů, které jsou pevně zakódovány tak, aby využívaly data z této čítače pomocí funkcí PerfLib V2 Consumer.

Požadavky

Požadavek	Hodnota
Minimální podporovaný klient	Windows Vista [pouze desktopové aplikace]
Minimální podporovaný server	Windows Server 2008 [jenom desktopové aplikace]