PCW_REGISTRATION_INFORMATION Struktur (wdm.h)

Artikel
02/07/2025

Die PCW_REGISTRATION_INFORMATION Struktur liefert Details zum Anbieter und zum Gegensatz. Die meisten Entwickler verwenden die funktionen CTRPP-generated RegisterXxx oder InitRegistrationInformationXxx anstelle dieser Struktur direkt zu verwenden.

Syntax

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;

Angehörige

Version

Der numerische Wert, der die Version der Leistungsindikatoren für Windows (PCW) angibt, die der Anbieter benötigt.

Unter Windows vor 10.0.19645 (NTDDI_VERSION < NTDDI_VERSION_MN) muss das feld Version auf PCW_VERSION_1 (0x100) festgelegt werden. Unter Windows 10.0.19645 und höher (NTDDI_VERSION >= NTDDI_VERSION_MN) kann dies auf PCW_VERSION_1 (0x100) oder PCW_VERSION_2 (0x200) festgelegt werden. Wenn das feld Version auf einen unbekannten Wert festgelegt ist, gibt PcwRegister STATUS_INVALID_PARAMETER_2 zurück.

Bei Verwendung der vom CTRPP generierten RegisterXxx- oder InitRegistrationInformationXxx-Funktionen wird das Version Feld auf PCW_CURRENT_VERSIONfestgelegt, was einem der folgenden Werte entspricht, abhängig vom Kompilierungswert von NTDDI_VERSION:

Zustand	wert PCW_CURRENT_VERSION
`NTDDI_VERSION < NTDDI_WIN10_FE`	PCW_VERSION_1 (0x0100)
`NTDDI_VERSION >= NTDDI_WIN10_FE`	PCW_VERSION_2 (0x0200)

Wenn Ihr Code mit NTDDI_VERSION >= NTDDI_WIN10_FE erstellt, aber auf einer früheren Version von Windows ausgeführt werden muss, müssen Sie Version = PCW_VERSION_1 wie in der Dokumentation für PcwRegister-beschrieben festlegen.

Name

Ein Zeiger auf die Zeichenfolge, die den Namen des zu registrierenden Zählers enthält. Diese Zeichenfolge darf nicht NULL oder leer sein.

Beachten Sie, dass Vergleiche von Gegenmengennamen nicht zwischen Groß- und Kleinschreibung unterschieden werden. Wenn derselbe Gegensatzname in zwei Gegensätzeregistrierungen verwendet wird, sammeln Verbraucher Daten aus beiden Registrierungen.

CounterCount

Die Anzahl der im parameter Counters bereitgestellten Deskriptoren.

Counters

Ein Array von Deskriptoren für die Zähler dieser Zählermenge. Die Informationen aus den Deskriptoren werden verwendet, wenn Zählerwerte aus Datenblöcken extrahiert werden, die von Aufrufen von PcwCreateInstance oder PcwAddInstancebereitgestellt werden.

Callback

Ein Zeiger auf die optionale PCW_CALLBACK Rückruffunktion, die den Anbieter über Ereignisse im Zusammenhang mit dieser Gegenmenge benachrichtigt. Dieses Feld kann NULL sein, wenn der Rückruf nicht erforderlich ist (d. h. wenn die Gegensatzinstanzen über PcwCreateInstance und PcwCloseInstanceverwaltet werden).

CallbackContext

Ein Zeigerwert, der bei jedem Aufruf an die vom Anbieter definierte PCW_CALLBACK Rückruffunktion übergeben wird.

Flags

Das feld Flags ist nur verfügbar, wenn NTDDI_VERSION >= NTDDI_WIN10_MN.

Das feld Flags wird ignoriert, wenn das feld Version kleiner als PCW_VERSION_2ist.

Das feld Flags ermöglicht ein spezielles Verhalten von PcwRegister. Wird auf eine Kombination aus einem oder mehreren PCW_REGISTRATION_FLAGS Werten festgelegt:

PCW_REGISTRATION_FLAGS	Bedeutung
PcwRegistrationNone (0x0)	Standard (keine speziellen Verhaltensweisen erforderlich).
PcwRegistrationSiloNeutral (0x1)	Gibt an, dass diese Registrierung für Verbraucher in allen Serversilos sichtbar sein sollte. Standardmäßig ist eine Registrierung nur für Verbraucher im Serversilos sichtbar, die beim Erstellen der Registrierung aktiv war (d. h. die Registrierung, die an den Thread angefügt wurde, als `PcwRegister` aufgerufen wurde).

Bemerkungen

Die PcwRegister--Funktion verwendet einen Info Parameter, der ein Zeiger auf diese Struktur ist.

CTRPP-generierte InitRegistrationInformationXxx-Funktion

Die meisten Entwickler müssen PCW_REGISTRATION_INFORMATION nicht direkt verwenden. Stattdessen kompilieren sie ein Manifest mit dem CTRPP-Tool und verwenden die Funktionen RegisterXxx oder InitRegistrationInformationXxx aus dem vom CTRPP generierten Header. Die generierte Register-Funktion ruft InitRegistrationInformation auf und ruft dann PcwRegister auf (details finden Sie unter PcwRegister-). Die generierte InitRegistrationInformation-Funktion sieht wie folgt aus:

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;
}

Die CTRPP-generierte InitRegistrationInformation-Funktion wird PräfixInitRegistrationInformationCounterset-benannt. Präfix- ist in der Regel leer, kann aber vorhanden sein, wenn der parameter -prefix in der Befehlszeile CTRPP verwendet wurde. Counterset- ist der Name des Zählers, wie im Manifest angegeben. Die generierte InitRegistrationInformation-Funktion initialisiert die bereitgestellte PCW_REGISTRATION_INFORMATION Struktur mit Werten aus den Funktionsparametern und dem Manifest.

Die ctRPP-generierte InitRegistrationInformation-Funktion kann optional überprüfen, ob die Größen der Strukturmember den im Manifest deklarierten Größen entsprechen. Standardmäßig ist CTRPP_VERIFY_COUNTER_SIZES auf 0 festgelegt und deaktiviert diese Überprüfung. Um diese Überprüfung zu aktivieren, #define CTRPP_VERIFY_COUNTER_SIZES 1 vor dem Einschließen des vom CTRPP generierten Headers. Wenn die Überprüfung aktiviert ist, löst ein Größenkonflikt einen Kompilierungsfehler aufgrund eines Fehlers der C_ASSERT Bedingung aus.