PCW_REGISTRATION_INFORMATION struttura (wdm.h)

Articolo
02/29/2024

La struttura PCW_REGISTRATION_INFORMATION fornisce informazioni dettagliate sul provider e sul contatore. La maggior parte degli sviluppatori userà le funzioni RegisterXxx o InitRegistrationInformationXxx generate da CTRPP anziché usare direttamente questa struttura.

Sintassi

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;

Members

Version

Valore numerico che specifica la versione dei contatori delle prestazioni per Windows (PCW) richiesta dal provider.

Quando viene eseguito in Windows prima della versione 10.0.19645 (NTDDI_VERSION < NTDDI_VERSION_MN), il Version campo deve essere impostato su PCW_VERSION_1 (0x100). Quando viene eseguito in Windows 10.0.19645 e versioni successive (NTDDI_VERSION >= NTDDI_VERSION_MN), è possibile impostare su PCW_VERSION_1 (0x100) o PCW_VERSION_2 (0x200). Se il Version campo è impostato su un valore non riconosciuto, PcwRegister restituirà STATUS_INVALID_PARAMETER_2.

Quando si utilizzano le funzioni RegisterXxx o InitRegistrationInformationXxx generate da CTRPP, il Version campo verrà impostato su PCW_CURRENT_VERSION, equivalente a uno dei valori seguenti, a seconda del valore di compilazione-time di NTDDI_VERSION:

Condizione	valore PCW_CURRENT_VERSION
`NTDDI_VERSION < NTDDI_WIN10_FE`	PCW_VERSION_1 (0x0100)
`NTDDI_VERSION >= NTDDI_WIN10_FE`	PCW_VERSION_2 (0x0200)

Se il codice viene compilato con NTDDI_VERSION >= NTDDI_WIN10_FE ma deve essere eseguito in una versione precedente di Windows, sarà necessario impostare Version = PCW_VERSION_1 come descritto nella documentazione di PcwRegister.

Name

Puntatore alla stringa contenente il nome del contatore da registrare. Questa stringa non deve essere NULL o vuota.

Si noti che i confronti dei nomi del contatore non sono distinzione tra maiuscole e minuscole. Se lo stesso nome del contatore viene usato in due registrazioni contatori, i consumer raccoglieranno i dati da entrambe le registrazioni.

CounterCount

Numero di descrittori forniti nel Counters parametro.

Counters

Matrice di descrittori per i contatori di questo contatore. Le informazioni dei descrittori verranno usate durante l'estrazione dei valori dei contatori dai blocchi di dati forniti dalle chiamate a PcwCreateInstance o PcwAddInstance.

Callback

Puntatore alla funzione di callback facoltativa PCW_CALLBACK che informa il provider di eventi correlati a questo contatore. Questo campo può essere NULL se il callback non è necessario (ad esempio, se le istanze del contatore verranno gestite tramite PcwCreateInstance e PcwCloseInstance).

CallbackContext

Valore del puntatore che verrà passato alla funzione di callback definita PCW_CALLBACK dal provider ogni volta che viene richiamato.

Flags

Il Flags campo è disponibile solo quando NTDDI_VERSION >= NTDDI_WIN10_MN.

Il Flags campo verrà ignorato se il Version campo è minore di PCW_VERSION_2.

Il Flags campo abilita un comportamento speciale di PcwRegister. Impostare su una combinazione di uno o più PCW_REGISTRATION_FLAGS valori:

PCW_REGISTRATION_FLAGS	Significato
PcwRegistrationNone (0x0)	Impostazione predefinita (nessun comportamento speciale richiesto).
PcwRegistrationSiloNeutral (0x1)	Indica che questa registrazione deve essere visibile ai consumer in tutti i silos del server. Per impostazione predefinita, una registrazione è visibile solo ai consumer nel silo del server attivo quando è stata creata la registrazione, ad esempio la registrazione collegata al thread quando `PcwRegister` è stata chiamata.

Commenti

La funzione PcwRegister accetta un parametro che rappresenta un Info puntatore a questa struttura.

Funzione InitRegistrationInformationXxx generata da CTRPP

La maggior parte degli sviluppatori non deve usare direttamente PCW_REGISTRATION_INFORMATION . Verranno invece compilati un manifesto con lo strumento CTRPP e useranno le funzioni RegisterXxx o InitRegistrationInformationXxx dall'intestazione generata da CTRPP. La funzione Register generata chiama InitRegistrationInformation e quindi chiama ( PcwRegister vedere PcwRegister per informazioni dettagliate). La funzione InitRegistrationInformation generata avrà un aspetto simile al seguente:

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 funzione InitRegistrationInformation generata da CTRPP verrà denominata PrefixInitRegistrationInformationCounterset. Il prefisso è in genere vuoto, ma può essere presente se il -prefix parametro è stato usato nella riga di comando CTRPP. Il contatore è il nome del contatore, come specificato nel manifesto. La funzione InitRegistrationInformation generata inizializzerà la struttura fornita PCW_REGISTRATION_INFORMATION con i valori dei parametri della funzione e del manifesto.

La funzione InitRegistrationInformation generata da CTRPP può verificare facoltativamente che le dimensioni dei membri della struttura corrispondano alle dimensioni dichiarate nel manifesto. Per impostazione predefinita, CTRPP_VERIFY_COUNTER_SIZES è impostato su 0, disabilitando questo controllo. Per abilitare questo controllo, #define CTRPP_VERIFY_COUNTER_SIZES 1 prima di includere l'intestazione generata da CTRPP. Se il controllo è abilitato, una mancata corrispondenza delle dimensioni attiverà un errore di compilazione a causa di un errore di errore della condizione di C_ASSERT.