PoFxRegisterDevice-Funktion (wdm.h)
Die PoFxRegisterDevice-Routine registriert ein Gerät mit dem Power Management Framework (PoFx).
Syntax
NTSTATUS PoFxRegisterDevice(
[in] PDEVICE_OBJECT Pdo,
[in] PPO_FX_DEVICE Device,
[out] POHANDLE *Handle
);
Parameter
[in] Pdo
Ein Zeiger auf ein physisches Geräteobjekt (PDO ). Dieser Parameter verweist auf eine DEVICE_OBJECT Struktur, die das physische Gerät darstellt, das registriert wird. Der Aufrufer ist der Besitzer der Energierichtlinie für das Gerät, das in der Regel der Funktionstreiber des Geräts ist.
[in] Device
Ein Zeiger auf eine vom Aufrufer zugewiesene PO_FX_DEVICE Struktur, die die Registrierungsinformationen für das Gerät enthält. Diese Struktur enthält Zeiger auf eine Reihe von Rückrufroutinen, die vom Gerätetreiber implementiert werden. PoFx ruft diese Routinen auf, um mit dem Treiber zu kommunizieren.
[out] Handle
Ein Zeiger auf einen Ort, an dem die Routine ein Handle schreibt, das die Registrierung des Geräts mit PoFx darstellt. Der Gerätetreiber übergibt dieses Handle als Eingabeparameter an die anderen PoFxXxx-Routinen , die er aufruft. Der Treiber muss zuerst PoFxRegisterDevice aufrufen, um das Gerät zu registrieren, bevor der Treiber andere PoFxXxx-Routinen aufruft, um das Gerät mit Energie zu verwalten.
Rückgabewert
PoFxRegisterDevice gibt STATUS_SUCCESS zurück, wenn die Routine das Gerät erfolgreich registriert. Mögliche Fehlerrückgabewerte umfassen die folgenden status-Codes.
Rückgabecode | Beschreibung |
---|---|
|
Pdo ist NULL; oder die PPO_FX_DEVICE Struktur hat eine ungültige Versionsnummer oder eine Komponentenanzahl von 0; oder die Anzahl der für eine Komponente angegebenen Leerlaufzustände ist 0; oder die Beschreibung eines Leerlaufzustands ist ungültig. |
|
Das Gerät ist nicht bereit. |
|
Für die Registrierung stehen nicht genügend Ressourcen zur Verfügung. |
Hinweise
Ein Gerätetreiber ruft diese Routine in der Regel vom IRP_MN_START_DEVICE Anforderungshandler des Treibers auf. Der Treiber darf diese Routine nicht aufrufen, bevor das Gerät eine IRP_MN_START_DEVICE-Anforderung empfängt. Das Gerät empfängt die erste IRP_MN_START_DEVICE Anforderung, wenn das Gerät zum ersten Mal gestartet wird. Das Gerät empfängt jedes Mal, wenn das Gerät nach dem Beenden des Ressourcenausgleichs neu gestartet wird, eine zusätzliche IRP_MN_START_DEVICE Anforderung. Ein PoFxRegisterDevice-Aufruf zum Registrieren eines bereits registrierten Geräts ist ein schwerwiegender Fehler und verursacht eine Fehlerüberprüfung. Beachten Sie, dass PoFx eine tiefgehende Kopie der Gerätestrukturen in den Arbeitsspeicher durchführt.
Bevor der Treiber PoFxRegisterDevice aufruft, muss das Gerät die folgenden Bedingungen erfüllen:
- Das Gerät (d. h. das PDO) ist noch nicht bei PoFx registriert.
- Das Gerät befindet sich im D0-Betriebszustand (vollständig eingeschaltet).
- Das Gerät befindet sich in der Ausführungsbedingung.
- Jede Komponente im Gerät befindet sich im Betriebszustand F0 (vollständig eingeschaltet).
- Jede Komponente befindet sich in der aktiven Bedingung.
Nachdem ein Treiber PoFxRegisterDevice aufgerufen hat , um ein Gerät bei PoFx zu registrieren, sind alle Komponenten im Gerät vollständig aktiviert und im aktiven Zustand, sodass der Treiber die Initialisierung der Hardware beenden kann. Um die aktive Energieverwaltung zu starten, muss der Treiber die PoFxStartDevicePowerManagement-Routine aufrufen.
Standardmäßig wechselt PoFxStartDevicePowerManagement alle Komponenten in die Leerlaufbedingung. Wenn der Treiber erfordert, dass sich eine Komponente unmittelbar nach dem Start der Energieverwaltung im aktiven Zustand befindet, muss der Treiber die Komponente explizit aktivieren, indem er die PoFxActivateComponent-Routine aufruft. Dieser Aufruf muss nach dem PoFxRegisterDevice-Aufruf , aber vor dem PoFxStartDevicePowerManagement-Aufruf erfolgen.
In der Regel ruft der kmDF-Treiber (Kernel-Mode Driver Framework) für ein Gerät mit nur einer Komponente PoFxRegisterDevice nicht auf, um das Gerät bei PoFx zu registrieren. Stattdessen erhält dieser Treiber ein PoFx-Registrierungshandle, wenn KMDF die Rückruffunktion EvtDeviceWdmPostPoFxRegisterDevice des Treibers aufruft. Weitere Informationen finden Sie unter Unterstützung mehrerer funktionsbezogener Energiezustände für Single-Component Geräte.
Informationen dazu, wie der KMDF-Treiber für ein Gerät mit mehreren Komponenten bei PoFx registriert wird, finden Sie unter Unterstützung mehrerer Funktionszustände für Multiple-Component-Geräte.
Anforderungen
Anforderung | Wert |
---|---|
Unterstützte Mindestversion (Client) | Verfügbar ab Windows 8. |
Zielplattform | Universell |
Header | wdm.h |
Bibliothek | Ntoskrnl.lib |
DLL | Ntoskrnl.exe |
IRQL | PASSIVE_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