structure PCW_REGISTRATION_INFORMATION (wdm.h)

Article
03/08/2023

La structure PCW_REGISTRATION_INFORMATION fournit des détails sur le fournisseur et le compteur. La plupart des développeurs utilisent les fonctions RegisterXxx ou InitRegistrationInformationXxx générées par CTRPP au lieu d’utiliser cette structure directement.

Syntaxe

typedef struct _PCW_REGISTRATION_INFORMATION {
  ULONG                   Version;
  PCUNICODE_STRING        Name;
  ULONG                   CounterCount;
  PPCW_COUNTER_DESCRIPTOR Counters;
  PPCW_CALLBACK           Callback;
  PVOID                   CallbackContext;
  PCW_REGISTRATION_FLAGS  Flags;
} PCW_REGISTRATION_INFORMATION, *PPCW_REGISTRATION_INFORMATION;

Membres

Version

Valeur numérique qui spécifie la version des compteurs de performances pour Windows (PCW) requise par le fournisseur.

Lors de l’exécution sur Windows avant la version 10.0.19645 (NTDDI_VERSION < NTDDI_VERSION_MN), le Version champ doit être défini sur PCW_VERSION_1 (0x100). En cas d’exécution sur Windows 10.0.19645 et versions ultérieures (NTDDI_VERSION >= NTDDI_VERSION_MN), il peut être défini sur PCW_VERSION_1 (0x100) ou PCW_VERSION_2 (0x200). Si le Version champ est défini sur une valeur non reconnue, PcwRegister retourne STATUS_INVALID_PARAMETER_2.

Lorsque vous utilisez les fonctions RegisterXxx ou InitRegistrationInformationXxx générées par CTRPP, le Version champ est défini PCW_CURRENT_VERSIONsur , ce qui équivaut à l’une des valeurs suivantes, en fonction de la valeur au moment de la compilation de NTDDI_VERSION:

Condition	valeur PCW_CURRENT_VERSION
`NTDDI_VERSION < NTDDI_WIN10_FE`	PCW_VERSION_1 (0x0100)
`NTDDI_VERSION >= NTDDI_WIN10_FE`	PCW_VERSION_2 (0x0200)

Si votre code est généré avec NTDDI_VERSION >= NTDDI_WIN10_FE mais doit s’exécuter sur une version antérieure de Windows, vous devez définir Version = PCW_VERSION_1 comme décrit dans la documentation de PcwRegister.

Name

Pointeur vers la chaîne qui contient le nom du compteur à inscrire. Cette chaîne ne doit pas être NULL ou vide.

Notez que les comparaisons de noms de contre-ensemble ne respectent pas la casse. Si le même nom de compteur est utilisé dans deux inscriptions de compteurs, les consommateurs collectent des données à partir des deux inscriptions.

CounterCount

Nombre de descripteurs fournis dans le Counters paramètre.

Counters

Tableau de descripteurs pour les compteurs de ce compteur. Les informations des descripteurs seront utilisées lors de l’extraction de valeurs de compteur à partir de blocs de données fournis par les appels à PcwCreateInstance ou PcwAddInstance.

Callback

Pointeur vers la fonction de rappel facultative PCW_CALLBACK qui avertit le fournisseur des événements liés à ce compteur. Ce champ peut avoir la valeur NULL si le rappel n’est pas nécessaire (c’est-à-dire si les instances de l’ensemble de compteurs sont gérées via PcwCreateInstance et PcwCloseInstance).

CallbackContext

Valeur de pointeur qui sera passée à la fonction de rappel définie par PCW_CALLBACK le fournisseur chaque fois qu’elle est appelée.

Flags

Le Flags champ n’est disponible que lorsque NTDDI_VERSION >= NTDDI_WIN10_MN.

Le Flags champ est ignoré si le Version champ est inférieur à PCW_VERSION_2.

Le Flags champ active le comportement spécial de PcwRegister. Définissez sur une combinaison d’une ou plusieurs PCW_REGISTRATION_FLAGS valeurs :

PCW_REGISTRATION_FLAGS	Signification
PcwRegistrationNone (0x0)	Par défaut (aucun comportement spécial requis).
PcwRegistrationSiloNeutral (0x1)	Indique que cette inscription doit être visible par les consommateurs dans tous les silos de serveurs. Par défaut, une inscription n’est visible que pour les consommateurs dans le silo de serveur actif lors de la création de l’inscription (c’est-à-dire l’inscription attachée au thread lors de l’appel `PcwRegister` ).

Remarques

La fonction PcwRegister prend un Info paramètre qui est un pointeur vers cette structure.

Fonction InitRegistrationInformationXxx générée par CTRPP

La plupart des développeurs n’ont pas besoin d’utiliser PCW_REGISTRATION_INFORMATION directement. Au lieu de cela, ils compilent un manifeste avec l’outil CTRPP et utilisent les fonctions RegisterXxx ou InitRegistrationInformationXxx à partir de l’en-tête généré par CTRPP. La fonction Register générée appelle InitRegistrationInformation, puis appelle (pour plus d’informations PcwRegister , consultez PcwRegister ). La fonction InitRegistrationInformation générée se présente comme suit :

EXTERN_C FORCEINLINE VOID
InitRegistrationInformationMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext,
    __out PCW_REGISTRATION_INFORMATION* RegInfo
    )
{
    static const UNICODE_STRING Name = RTL_CONSTANT_STRING(L"My Counterset Name");
    static const PCW_COUNTER_DESCRIPTOR Descriptors[] = {
        { 0, 0, FIELD_OFFSET(MY_COUNTER_DATA, MyData1), RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData1)},
        { 1, 0, FIELD_OFFSET(MY_COUNTER_DATA, MyData2), RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData2)},
    };

#if CTRPP_VERIFY_COUNTER_SIZES

    //
    // Verify that structure member size matches manifest counter size.
    //

    C_ASSERT(RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData1) == sizeof(ULONGLONG));
    C_ASSERT(RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData2) == sizeof(ULONG));

#endif // CTRPP_VERIFY_COUNTER_SIZES

    PAGED_CODE();

    RtlZeroMemory(RegInfo, sizeof(*RegInfo));
    RegInfo->Version = PCW_CURRENT_VERSION;
    RegInfo->Name = &Name;
    RegInfo->CounterCount = RTL_NUMBER_OF(Descriptors);
    RegInfo->Counters = (PCW_COUNTER_DESCRIPTOR*)Descriptors;
    RegInfo->Callback = Callback;
    RegInfo->CallbackContext = CallbackContext;
}

La fonction InitRegistrationInformation générée par CTRPP sera nommée PréfixeInitRegistrationInformationCounterset. Le préfixe est généralement vide, mais peut être présent si le -prefix paramètre a été utilisé sur la ligne de commande CTRPP. Counterset est le nom du compteur, comme spécifié dans le manifeste. La fonction InitRegistrationInformation générée initialise la structure fournie PCW_REGISTRATION_INFORMATION avec les valeurs des paramètres de fonction et du manifeste.

La fonction InitRegistrationInformation générée par CTRPP peut éventuellement vérifier que les tailles des membres de la structure correspondent aux tailles déclarées dans le manifeste. Par défaut, CTRPP_VERIFY_COUNTER_SIZES est défini sur 0, ce qui désactive cette case activée. Pour activer cette case activée, #define CTRPP_VERIFY_COUNTER_SIZES 1 avant d’inclure l’en-tête généré par CTRPP. Si le case activée est activé, une incompatibilité de taille déclenche une erreur de compilation en raison de l’échec de la condition C_ASSERT.