PcwRegister-Funktion (wdm.h)

  • Artikel

Die PcwRegister Funktion erstellt eine neue Zählersetregistrierung. Die meisten Entwickler verwenden eine von CTRPP generierte RegisterXxx-Funktion, anstatt diese Funktion direkt aufzurufen.

Syntax

NTSTATUS PcwRegister(
  [out] PPCW_REGISTRATION             *Registration,
  [in]  PPCW_REGISTRATION_INFORMATION Info
);

Parameter

[out] Registration

Ein Zeiger auf eine PPCW_REGISTRATION. Empfängt das Handle für die neue Registrierung. Die Registrierung sollte mit PcwUnregister geschlossen werden.

[in] Info

Ein Zeiger auf eine PCW_REGISTRATION_INFORMATION-Struktur , die die Details zum zu registrierenden Zählerset enthält.

Rückgabewert

PcwRegister gibt einen der folgenden Werte zurück:

Rückgabecode Beschreibung
STATUS_SUCCESS Das Zählerset wurde erfolgreich registriert.
STATUS_INTEGER_OVERFLOW Die Anzahl der leistungsindikatoren, die von dieser Registrierung verfügbar gemacht werden, überschreitet die maximal unterstützte Anzahl.
STATUS_NO_MEMORY Es ist nicht genügend Speicherplatz verfügbar, um Arbeitsspeicher für die Leistungsindikatoren zuzuweisen.
STATUS_INVALID_PARAMETER_2 Im Parameter wurde ein Problem gefunden Info . Einige mögliche Ursachen finden Sie unten.

PcwRegister kann in den folgenden Fällen zurückgegeben STATUS_INVALID_PARAMETER_2 werden:

  • Das Info->Name->Length Feld ist 0 oder ist kein Vielfaches von sizeof(WCHAR).

  • Das Info->Version Feld stimmt nicht mit einem unterstützten Wert für diese Version von Windows überein. 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.

  • Das Info->Flags Feld enthält einen Wert, der von der ausgeführten Windows-Version nicht erkannt wird.

Hinweise

Der Anbieter ruft diese Funktion auf, um eine neue Countersetregistrierung zu erstellen. Alle Eingabeargumente werden erfasst, sodass der Aufrufer keine Kopie davon behalten muss.

Standardmäßig ist das neue Counterset nur für das Serversilos sichtbar, das zum Zeitpunkt der Registrierung aktiv war (d. h. PcwRegister ordnet die neu erstellte Registrierung dem Serversilos zu, das beim PcwRegister Aufruf an den Thread angefügt wurde). Wenn Sie auf Windows 10.0.19645 und höher () ausgeführt werden,NTDDI_VERSION >= NTDDI_VERSION_MN können Sie eine Gegensetregistrierung erstellen, die für alle Serversilos sichtbar ist, indem PCW_REGISTRATION_INFORMATION::Version Sie auf PCW_VERSION_2 festlegen und auf PcwRegistrationSiloNeutralfestlegenPCW_REGISTRATION_INFORMATION::Flags.

CTRPP-generierte RegisterXxx-Funktion

Die meisten Entwickler müssen nicht direkt aufrufen PcwRegister . Stattdessen kompilieren sie ein Manifest mit dem CTRPP-Tool und verwenden die Funktion RegisterXxx aus dem von CTRPP generierten Header. Die generierte Funktion sieht wie folgt aus:

EXTERN_C FORCEINLINE NTSTATUS
RegisterMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext
    )
{
    PCW_REGISTRATION_INFORMATION RegInfo;

    PAGED_CODE();

    InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

    return PcwRegister(&MyCounterset, &RegInfo);
}

Die von CTRPP generierte Register-Funktion heißt Präfixregisterzählerset. 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 Register-Funktion ruft die Funktion PrefixInitRegistrationInformationCounterset auf, um eine PCW_REGISTRATION_INFORMATION Struktur zu initialisieren, und ruft dann auf PcwRegister , um eine neue Registrierung zu erstellen und das Handle in der globalen Counterset-Variable zu speichern (deklariert im ctRPP-generierten Header im MyCounterset Beispiel).

In einigen Fällen ist die von CTRPP generierte Add-Funktion möglicherweise nicht geeignet.

  • Wenn Sie mit NTDDI_VERSION >= NTDDI_VERSION_FE kompilieren, aber unter früheren Versionen von Windows ausführen müssen, funktioniert die von CTRPP generierte Register-Funktion nicht, da sie festlegt RegInfo.Version = PCW_CURRENT_VERSION. Wenn NTDDI_VERSION >= NTDDI_VERSION_FEwird auf PCW_CURRENT_VERSIONPCW_VERSION_2festgelegt, wodurch PcwRegister ein Fehler zurückgegeben wird.

  • Wenn Sie mehrere Countersetregistrierungen unterstützen müssen (z. B. zur Unterstützung einer separaten Registrierung pro Serversilos), funktioniert die von CTRPP generierte Register-Funktion nicht, da sie das zurückgegebene Handle in einer globalen Variablen speichert.

  • Wenn Sie eine siloneutrale Zählersetregistrierung erstellen möchten, funktioniert die von CTRPP generierte Register-Funktion nicht, da es keine Möglichkeit gibt, den Wert von vor dem Aufrufen PcwRegistervon RegInfo.Flags zu ändern.

Verwenden Sie in diesen Fällen Code wie den folgenden, anstatt die von CTRPP generierte Register-Funktion aufzurufen:

PCW_REGISTRATION_INFORMATION RegInfo;
InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

// Modify RegInfo as needed,
// e.g. RegInfo.Version = PCW_VERSION_1,
// or RegInfo.Flags = PcwRegistrationSiloNeutral.

// If needed, use another variable to store the handle instead of MyCounterset.
Status = PcwRegister(&MyCounterset, &RegInfo);

Die von CTRPP generierte Funktion InitRegistrationInformationXxx initialisiert die RegInfo Struktur basierend auf Deklarationen aus dem Manifest. Weitere Informationen zur generierten InitRegistrationInformation-Funktion finden Sie in der Dokumentation für PCW_REGISTRATION_INFORMATION.

Wenn Sie ihre eigenen Handle-Variablen anstelle von Counterset zum Speichern des Handles verwenden, müssen Sie möglicherweise auch direkt aufrufen PcwUnregister , PcwCreateInstance anstatt die von CTRPP generierten Funktionen UnregisterXxx und CreateXxx zu verwenden.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar in Windows 7 und späteren Windows-Versionen.
Zielplattform Universell
Header wdm.h (include Wdm.h, Ntddk.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL IRQL <= APC_LEVEL

Weitere Informationen

PcwUnregister

_PCW_REGISTRATION_INFORMATION