PCW_REGISTRATION_INFORMATION-Struktur (wdm.h)

Artikel
02/27/2024

Die PCW_REGISTRATION_INFORMATION-Struktur enthält Details zum Anbieter und zum Counterset. Die meisten Entwickler verwenden die von CTRPP generierten Funktionen RegisterXxx oder InitRegistrationInformationXxx, anstatt diese 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;

Member

Version

Der numerische Wert, der die vom Anbieter erforderliche Version von Leistungsindikatoren für Windows (PCW) angibt.

Bei Ausführung unter Windows vor 10.0.19645 (NTDDI_VERSION < NTDDI_VERSION_MN) muss das Version Feld auf PCW_VERSION_1 (0x100) festgelegt werden. Bei Ausführung auf 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 Version Feld auf einen nicht erkannten Wert festgelegt ist, PcwRegister gibt STATUS_INVALID_PARAMETER_2 zurück.

Wenn Sie die von CTRPP generierten Funktionen RegisterXxx oder InitRegistrationInformationXxx verwenden, wird das Version Feld auf PCW_CURRENT_VERSIONfestgelegt, was einem der folgenden Werte entspricht, abhängig vom Kompilierzeitwert von NTDDI_VERSION:

Bedingung	PCW_CURRENT_VERSION Wert
`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 festlegen Version = PCW_VERSION_1 , wie in der Dokumentation für PcwRegister beschrieben.

Name

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

Beachten Sie, dass beim Vergleich von Countersetnamen die Groß-/Kleinschreibung nicht beachtet wird. Wenn derselbe Countersetname in zwei Counterset-Registrierungen verwendet wird, sammeln Consumer Daten aus beiden Registrierungen.

CounterCount

Die Anzahl der im Counters Parameter angegebenen Deskriptoren.

Counters

Ein Array von Deskriptoren für die Indikatoren dieses Countersets. Die Informationen aus den Deskriptoren werden verwendet, wenn Leistungsindikatorenwerte aus Datenblöcken extrahiert werden, die durch Aufrufe PcwCreateInstance von oder PcwAddInstancebereitgestellt werden.

Callback

Ein Zeiger auf die optionale PCW_CALLBACK Rückruffunktion, die den Anbieter über Ereignisse im Zusammenhang mit diesem Counterset benachrichtigt. Dieses Feld kann NULL sein, wenn der Rückruf nicht erforderlich ist (d. h. wenn die Countersetinstanzen ü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 Flags Feld ist nur verfügbar, wenn NTDDI_VERSION >= NTDDI_WIN10_MN.

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

Das Flags Feld aktiviert ein spezielles Verhalten von PcwRegister. Legen Sie eine Kombination aus mindestens einem PCW_REGISTRATION_FLAGS Wert fest:

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

Hinweise

Die PcwRegister-Funktion akzeptiert 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 von CTRPP generierten Header. Die generierte Register-Funktion ruft InitRegistrationInformation auf und ruft dann auf PcwRegister (Weitere Informationen 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 von CTRPP generierte Funktion InitRegistrationInformation heißt PrefixInitRegistrationInformationCounterset. Das Präfix ist normalerweise leer, kann aber vorhanden sein, wenn der -prefix Parameter in der CTRPP-Befehlszeile verwendet wurde. Counterset ist der Name des Countersets, wie im Manifest angegeben. Die generierte InitRegistrationInformation-Funktion initialisiert die bereitgestellte PCW_REGISTRATION_INFORMATION Struktur mit Werten aus den Funktionsparametern und dem Manifest.

Die von CTRPP generierte Funktion InitRegistrationInformation kann optional überprüfen, ob die Größen der Strukturmember den im Manifest deklarierten Größen entsprechen. Standardmäßig ist auf 0 festgelegt, CTRPP_VERIFY_COUNTER_SIZES und diese Überprüfung wird deaktiviert. Um diese Überprüfung zu aktivieren, #define CTRPP_VERIFY_COUNTER_SIZES 1 bevor Sie den von CTRPP generierten Header einschließen. Wenn die Überprüfung aktiviert ist, löst ein Größenkonflikt aufgrund eines Fehlers der C_ASSERT Bedingung einen Kompilierfehler aus.