Partager via

CTRPP

  • Article

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 nécessaires aux consommateurs de votre fournisseur, et génère un .h en-tête avec le code que vous utilisez pour fournir les données de votre 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
inputFile Obligatoire: Spécifie le nom du .man fichier (manifeste XML) qui définit vos compteurs.
-ocodeFile Obligatoire: Spécifie le nom du fichier de .h code à générer par CTRPP. Ce fichier contient des fonctions d’assistance inline C/C++ qui simplifient l’initialisation et la non initialisation de votre fournisseur.
-rcrcFile 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.
-chsymFile Spécifie le nom du fichier de symboles facultatif .h à générer par CTRPP. Ce fichier contient des symboles C/C++ pour les noms et GUID de chaque ensemble de compteurs dans le fournisseur.
Préfixe -prefix Spécifie le préfixe à utiliser pour les variables et 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 permettant de spécifier le nom des fonctions de rappel ControlCallback, AllocateMemory et FreeMemory . Cet argument a le même effet que l’inclusion de l’attribut callback dans l’élément provider .
-migrateoutputFile Au lieu de générer des .h fichiers et .rc , met à niveau le manifeste inputFile vers la dernière version et l’enregistre dans outputFile. Ce commutateur ne peut pas être utilisé avec d’autres commutateurs. Utilisation : CTRPP -migrate NewFile.man OldFile.man
-BackCompat Déconseillée: 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 n’est pas compatible avec les versions antérieures de Windows (le chargement du pilote échoue en raison d’API manquantes Pcw*** ). Définissez -BackCompat pour activer la compatibilité avec les versions antérieures de Windows. Le pilote charge dynamiquement les API nécessaires et le code généré désactive le fournisseur en mode silencieux si les API ne sont pas disponibles.
-MemoryRoutines Déconseillée: Lorsqu’il est utilisé avec le -Legacy commutateur, inclut 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éritage Déconseillée: Génère des *.hfichiers , *.c, *.rcet *_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 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 seront nommés en fonction du nom du manifeste et seront écrits dans le répertoire qui contenait le manifeste. Utilisation : CTRPP -legacy OldFile.man

Notes

L’outil CTRPP génère un .h fichier de code, un fichier de .rc ressources et génère éventuellement 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 des compteurs du fournisseur.

Important

Les ressources de ce fichier doivent être incluses dans votre fichier binaire de fournisseur et le chemin d’accès complet au fichier binaire du fournisseur doit être inscrit lors de l’installation du manifeste de votre fournisseur. Les consommateurs qui ne peuvent pas localiser et charger les ressources ne pourront pas utiliser les compteurs de votre fournisseur.

Les ressources de chaîne doivent être gérées comme suit :

  • Le développeur modifie le fichier manifeste du fournisseur (.man) pour définir l’attribut applicationIdentity du fournisseur sur le nom d’un fichier binaire de fournisseur (.DLL, .SYS ou .EXE) qui contiendra les ressources de 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 .rc fichier.
  • L’outil RC (compilateur de ressources) compile les données du fichier généré par .rc CTRPP pour générer un .res fichier contenant les ressources binaires. Pour ce faire, vous pouvez compiler directement le fichier généré .rc par CTRPP ou en compilant un autre .rc fichier qui inclut le fichier généré .rc par CTRPP via une #include directive.
  • L’éditeur de liens incorpore les données du fichier généré par .res RC dans le fichier 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’attribut applicationIdentity 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 combine le chemin du manifeste spécifié avec l’attribut du applicationIdentity manifeste pour former le chemin d’accès complet.
    • Sinon, utilisez lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path". lodctr combine le chemin binaire spécifié avec l’attribut du applicationIdentity 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 valeur de la ApplicationIdentity clé HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>}de Registre .
    • Si le fichier binaire utilise l’interface utilisateur utilisateur (MUI) pour la localisation, veillez à copier le fichier MUI avec le fichier binaire.
  • Pendant la collecte de contre-ensembles, le consommateur utilise le chemin d’accès complet enregistré au fichier binaire du fournisseur pour localiser et charger les chaînes nécessaires à partir des ressources binaires 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 providerType fournisseur est défini sur userMode, le fichier de code généré contient les définitions suivantes qui sont utiles pour coder un fournisseur en mode utilisateur :

  • Fonction d’initialisation du fournisseur nommée préfixeCounterInitialize.
  • Fonction de nettoyage du fournisseur nommée préfixeCounterCleanup.
  • Variable de fournisseur globale qui stocke le handle de fournisseur ouvert par la fonction counterInitialize de préfixe. Le nom de la variable est la valeur de l’attribut symbol de l’élément provider 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 ensemble de compteurs, une variable GUID de jeu de compteurs global avec le GUID de jeu de compteurs. Le nom de la variable est la valeur de l’attribut de symbol l’élément counterSet plus le suffixe « GUID », par exemple MyCounterSetGUID. 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 id compteur. Le nom de la macro est la valeur de l’attribut de l’élément countersymbol . 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, préfixe 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 providerType fournisseur est défini sur kernelMode, le fichier de code généré contient les définitions suivantes qui sont utiles pour coder les compteurs d’un fournisseur en mode noyau :

  • Fonction d’initialisation de jeu de compteurs nommée prefixRegisterCounterset. Cette fonction remplit une structure RegInfo , puis appelle PcwRegister, en plaçant le handle d’inscription de jeu de compteurs résultant dans la variable counterset globale.
  • Fonction de nettoyage de jeu de compteurs nommée prefixUnregisterCounterset. Cette fonction appelle PcwUnregister sur le handle d’inscription de jeu de compteurs dans la variable counterset globale.
  • Une fonction de création instance nommée préfixeCreateCounterset. Cette fonction remplit un tableau de structures PcwData , puis appelle PcwCreateInstance à l’aide du handle d’inscription de jeu de compteurs dans la variable counterset globale.
  • Une fonction de nettoyage instance nommée préfixeCloseCounterset. Cette fonction appelle PcwCloseInstance.
  • Une fonction de création de rapports instance nommée préfixeAddCounterset à utiliser à partir de la fonction de rappel de jeu de compteurs. Cette fonction remplit un tableau de structures PcwData , puis appelle PcwAddInstance.
  • Sdk Windows 20H1 et versions ultérieures : Fonction d’initialisation RegInfo nommée préfixeInitRegistrationInformationCounterset à utiliser dans des scénarios avancés. Cette fonction remplit une structure RegInfo . Cette fonction peut être utilisée dans les cas où le préfixeRegisterCounterset généré 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, préfixe 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’auront pas de préfixe.

Notes

La fonction AddCounterset de préfixe générée est utilisée lorsque vous avez un rappel de jeu de compteurs. Les fonctions CreateCounterset etCloseCounterset de préfixe générées sont utilisées lorsque vous n’avez pas de rappel de jeu de compteurs.

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 GUID de chaque compteur 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 compteur à l’aide des fonctions De consommation PerfLib V2.

Spécifications

Condition requise Valeur
Client minimal pris en charge Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau uniquement]