CTRPP
L’outil CTRPP est un pré-processeur qui analyse et valide le manifeste pour votre fournisseur v2. L’outil génère des .rc ressources avec les chaînes requises par les consommateurs de votre fournisseur et génère un .h en-tête avec le code que vous utilisez pour fournir vos données de compteur. Vous devez exécuter l’outil CTRPP pendant la génération de votre fournisseur. Vous devez utiliser le code généré comme point de départ lors du développement de votre fournisseur au lieu d’essayer de générer ce code vous-même.
ctrpp -o codeFile -rc rcFile [-legacy] [-MemoryRoutines] [-NotificationCallback] [-prefix prefix] [-ch symFile] [-backcompat] inputFile
Arguments
| Option | Description |
|---|---|
| FichierEntrée | Obligatoire : Spécifie le nom du .man fichier (manifeste XML) qui définit vos compteurs. |
| -o CodeFile | Obligatoire : Spécifie le nom du .h fichier de code à générer par ctrpp. Ce fichier contient des fonctions d’assistance inline C/C++ qui simplifient l’initialisation et la désinitialisation de votre fournisseur. |
| -RC rcFile | Obligatoire : Spécifie le nom du .rc fichier de ressources à générer par ctrpp. Ce fichier contient la table de chaînes du fournisseur. |
| -ch symFile | Spécifie le nom du fichier de symboles facultatifs .h à générer par ctrpp. Ce fichier contient des symboles C/C++ pour les noms et les GUID de chaque CounterSet dans le fournisseur. |
| - préfixe préfixe | Spécifie le préfixe à utiliser pour les variables et les fonctions définies dans le fichier d’en-tête généré. |
| -NotificationCallback | Modifie la signature par défaut de la fonction CounterInitialize pour inclure des paramètres pour la spécification du nom des fonctions de rappel ControlCallback, AllocateMemoryet FreeMemory . Cet argument a le même effet que l’inclusion callback de l’attribut dans l’élément Provider . |
| -migrer outputfile | Au lieu de générer et de créer des .h .rc fichiers, met à niveau le manifeste FichierEntrée vers la dernière version et l’enregistre dans FichierSortie. Ce commutateur ne peut pas être utilisé avec d’autres commutateurs. Utilisation : CTRPP -migrate NewFile.man OldFile.man |
| -Incompatibilité | Déconseillé : la prise en charge des fournisseurs en mode noyau a été ajoutée dans Windows 7. par défaut, le code généré par CTRPP pour les fournisseurs en mode noyau est incompatible avec les versions antérieures de Windows (le pilote ne peut pas se charger en raison d’api manquantes Pcw*** ). Défini -BackCompat pour activer la compatibilité avec les versions antérieures de Windows. Le pilote chargera dynamiquement les API nécessaires et le code généré désactivera silencieusement le fournisseur si les API ne sont pas disponibles. |
| -MemoryRoutines | Déconseillé : En cas d’utilisation avec le -Legacy commutateur, comprend des modèles pour les routines de mémoire dans le code généré. Sinon, cet argument a le même effet que le -NotificationCallback commutateur. |
| -Hérité | Déconseillé : génère *.h des *.c fichiers,, *.rc et *_r.h à l’aide des modèles de code Windows Vista (génère PerfAutoInitialize et PerfAutoCleanup au lieu de CounterInitialize et CounterCleanup). Ce commutateur peut être utilisé avec -MemoryRoutines et -NotificationCallback , mais il ne peut pas être utilisé avec d’autres commutateurs. N’utilisez pas les commutateurs -o ou -RC avec ce commutateur. Les fichiers générés sont nommés en fonction du nom du manifeste et sont écrits dans le répertoire qui contenait le manifeste. Utilisation : CTRPP -legacy OldFile.man |
Remarques
L’outil CTRPP génère un fichier de .h code, un .rc fichier de ressources et, éventuellement, génère un .h fichier de symboles.
Utilisation du fichier de ressources généré
L’outil CTRPP génère un .rc fichier de ressources qui contient les chaînes localisables nécessaires aux consommateurs du countersets du fournisseur.
Important
Les ressources de ce fichier doivent être incluses dans votre binaire de fournisseur et le chemin d’accès complet au fichier binaire du fournisseur doit être inscrit pendant l’installation du manifeste de votre fournisseur. Les consommateurs qui ne parviennent pas à localiser et à charger les ressources ne pourront pas utiliser les countersets de votre fournisseur.
Les ressources de type chaîne doivent être gérées comme suit :
- Le développeur modifie le fichier manifeste du fournisseur (
.man) afin de définir l'applicationIdentityattribut du fournisseur sur le nom d’un fournisseur (.DLL, .SYS ou .EXE) qui contiendra les ressources de type chaîne pour le fournisseur et sera installé dans le cadre du composant fournisseur. - L’outil CTRPP lit le manifeste du fournisseur et génère un
.rcfichier. - L’outil RC (compilateur de ressources) compile les données du fichier généré par ctrpp
.rcpour générer un.resfichier contenant les ressources binaires. Pour ce faire, vous pouvez compiler directement le fichier généré par CTRPP.rcou en compilant un autre.rcfichier qui comprend le fichier généré par ctrpp.rcvia une#includedirective. - L’éditeur de liens incorpore les données du fichier généré par RC
.resdans le binaire du fournisseur. - Pendant l’installation, le fichier binaire du fournisseur est copié sur le système de l’utilisateur et le manifeste du fournisseur est enregistré à l’aide de l' outil lodctr. L’outil lodctr convertit l'
applicationIdentityattribut du manifeste du fournisseur en chemin d’accès complet et enregistre le chemin d’accès complet au fichier binaire du fournisseur dans le registre.- Si le fichier binaire du fournisseur se trouve dans le même répertoire que le manifeste, utilisez :
lodctr.exe /m:"C:\full\manifest\path\manifest.man". lodctr associe le chemin d’accès du manifeste spécifié à l’attribut du manifesteapplicationIdentitypour former le chemin d’accès complet. - Sinon, utilisez
lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path". lodctr associe le chemin d’accès binaire spécifié à l'applicationIdentityattribut du manifeste pour former le chemin d’accès complet. - À des fins de diagnostic, vous pouvez inspecter le chemin d’accès complet enregistré en vérifiant la
ApplicationIdentityvaleur de la clé de RegistreHKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>}. - Si le fichier binaire utilise MUI pour la localisation, veillez à copier le fichier MUI avec le fichier binaire.
- Si le fichier binaire du fournisseur se trouve dans le même répertoire que le manifeste, utilisez :
- Pendant la collection CounterSet, le consommateur utilise le chemin d’accès complet enregistré au fichier binaire du fournisseur pour rechercher et charger les chaînes nécessaires à partir des ressources du binaire du fournisseur.
Utilisation du fichier de code généré dans un fournisseur en mode utilisateur
L’outil CTRPP génère un .h fichier de code C/C++. Si l’attribut du manifeste du fournisseur providerType a la valeur userMode , le fichier de code généré contient les définitions suivantes qui sont utiles pour le codage d’un fournisseur en mode utilisateur :
- Une fonction d’initialisation du fournisseur nommée * préfixe * CounterInitialize.
- Une fonction de nettoyage du fournisseur nommée * préfixe * CounterCleanup.
- Variable globale Provider _ qui stocke le handle du fournisseur ouvert par la fonction _ _prefix_CounterInitialize. Le nom de la variable est la valeur de l'
symbolattribut de l'providerélément dans le manifeste. Cette variable doit être utilisée dans les appels àPerfCreateInstance,PerfDeleteInstanceet à d’autres API pour contrôler les données de votre fournisseur. - Pour chaque CounterSet, une variable **GUID * CounterSet *** globale avec le GUID du CounterSet. Le nom de la variable est la valeur de l’attribut de l'
counterSetélémentsymbolplus le suffixe « GUID », par exempleMyCounterSetGUID. Cette variable doit être utilisée dans les appels àPerfCreateInstance,PerfDeleteInstanceet à d’autres API pour contrôler les données de votre fournisseur. - Pour chaque compteur, une macro de compteur avec la valeur du compteur
id. Le nom de la macro est la valeur de l’attribut de l'counterélémentsymbol. Cette macro doit être utilisée dans les appels àPerfSetCounterRefValue,PerfSetULongLongCounterValueet à d’autres API pour définir les données de votre fournisseur.
Dans les noms de fonction, prefix fait référence à la valeur du -prefix paramètre de ligne de commande. Si le -prefix paramètre n’est pas utilisé, les fonctions sont nommées CounterInitialize et CounterCleanup .
Utilisation du fichier de code généré dans un fournisseur en mode noyau
L’outil CTRPP génère un .h fichier de code C/C++. Si l’attribut du manifeste du fournisseur providerType a la valeur kernelMode , le fichier de code généré contient les définitions suivantes qui sont utiles pour coder les countersets d’un fournisseur en mode noyau :
- Une fonction d’initialisation CounterSet nommée prefix Register CounterSet. Cette fonction remplit une structure RegInfo , puis appelle PcwRegister, en plaçant le handle d’inscription du CounterSet résultant dans la variable globale CounterSet .
- Une fonction de nettoyage du CounterSet nommée Unregister CounterSet. Cette fonction appelle PcwUnregister sur le handle d’inscription du CounterSet dans la variable globale CounterSet .
- Une fonction de création d’instance nommée prefix Create CounterSet. Cette fonction remplit un tableau de structures PcwData , puis appelle PcwCreateInstance à l’aide du handle d’inscription du CounterSet dans la variable globale CounterSet .
- Une fonction de nettoyage d’instance nommée « préfixe», fermer CounterSet. Cette fonction appelle PcwCloseInstance.
- Une fonction de création de rapports d’instance nommée prefix Add CounterSet à utiliser à partir de la fonction de rappel du CounterSet. Cette fonction remplit un tableau de structures PcwData , puis appelle PcwAddInstance.
- SDK Windows 20H1 et versions ultérieures : Une fonction d’initialisation RegInfo nommée prefix InitRegistrationInformation CounterSet pour une utilisation dans des scénarios avancés. Cette fonction remplit une structure RegInfo . Cette fonction peut être utilisée dans les cas où le Registre de préfixe généré CounterSet ne répond pas à vos besoins, par exemple lorsque vous souhaitez personnaliser les valeurs dans la structure RegInfo ou lorsque vous souhaitez stocker le handle retourné dans une autre variable.
Dans les noms de fonction, prefix fait référence à la valeur du -prefix paramètre de ligne de commande. Si le -prefix paramètre n’est pas utilisé, les fonctions n’ont pas de préfixe.
Notes
La fonction Add CounterSet de préfixe générée est utilisée quand vous avez un rappel de CounterSet. Le préfixe généré Create CounterSet et le préfixe de la fonction CounterSet sont utilisés lorsque vous n’avez pas de rappel CounterSet.
Utilisation du fichier de symboles généré
Si le paramètre -ch est spécifié sur la ligne de commande, l’outil ctrpp génère un .h fichier de symboles. Ce fichier contient les symboles C/C++ pour les noms et les GUID de chaque CounterSet dans le fournisseur. Les symboles peuvent être utilisés lors de l’écriture de programmes codés en dur pour consommer les données de ce CounterSet à l’aide des fonctions de consommateur de Perflib v2.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows [Applications de bureau Vista uniquement] |
| Serveur minimal pris en charge | Windows Serveur 2008 [ applications de bureau uniquement] |