PcwRegister-Funktion (wdm.h)
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 vonsizeof(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 dasVersion
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 PcwRegistrationSiloNeutral
festlegenPCW_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 festlegtRegInfo.Version = PCW_CURRENT_VERSION
. WennNTDDI_VERSION >= NTDDI_VERSION_FE
wird aufPCW_CURRENT_VERSION
PCW_VERSION_2
festgelegt, wodurchPcwRegister
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
PcwRegister
vonRegInfo.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
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für