structure PCW_REGISTRATION_INFORMATION (wdm.h)

Article
02/07/2025

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

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 champ Version doit être défini sur PCW_VERSION_1 (0x100). Lors de l’exécution sur Windows 10.0.19645 et versions ultérieures (NTDDI_VERSION >= NTDDI_VERSION_MN), cela peut être défini sur PCW_VERSION_1 (0x100) ou PCW_VERSION_2 (0x200). Si le champ Version 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 champ Version est défini sur PCW_CURRENT_VERSION, ce qui équivaut à l’une des valeurs suivantes, en fonction de la valeur de 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 s’appuie sur 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 relative à 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 compteurs 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 paramètre Counters.

Counters

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

Callback

Pointeur vers la fonction de rappel facultative PCW_CALLBACK qui informe le fournisseur des événements liés à ce compteur. Ce champ peut être NULL si le rappel n’est pas nécessaire (par exemple, si les instances de compteurs seront gérées via PcwCreateInstance et PcwCloseInstance).

CallbackContext

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

Flags

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

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

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

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

Remarques

La fonction PcwRegister prend un paramètre Info 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 PcwRegister (voir PcwRegister pour plus d’informations). 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. préfixe est généralement vide, mais peut être présent si le paramètre -prefix a été utilisé sur la ligne de commande CTRPP. Counterset est le nom du compteur, tel que spécifié dans le manifeste. La fonction InitRegistrationInformation générée initialise la structure PCW_REGISTRATION_INFORMATION fournie avec des 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, en désactivant cette vérification. Pour activer cette vérification, #define CTRPP_VERIFY_COUNTER_SIZES 1 avant d’inclure l’en-tête généré par CTRPP. Si la vérification est activée, une incompatibilité de taille déclenche une erreur de compilation en raison d’une défaillance de la condition de C_ASSERT.