PoRequestPowerIrp-Funktion (wdm.h)
Die PoRequestPowerIrp-Routine weist eine Energie-IRP zu und sendet sie an den obersten Treiber im Gerätestapel für das angegebene Gerät.
Syntax
NTSTATUS PoRequestPowerIrp(
[in] PDEVICE_OBJECT DeviceObject,
[in] UCHAR MinorFunction,
[in] POWER_STATE PowerState,
[in, optional] PREQUEST_POWER_COMPLETE CompletionFunction,
[in, optional] __drv_aliasesMem PVOID Context,
[out] PIRP *Irp
);
Parameter
[in] DeviceObject
Ein Zeiger auf das Ziel DEVICE_OBJECT für die IRP. In Windows 2000 und höheren Versionen von Windows kann dieser Parameter auf ein physisches Geräteobjekt (PDO) oder ein funktionales Geräteobjekt (Functional Device Object, FDO) verweisen. In Windows 98/Me muss dieser Parameter auf die PDO des zugrunde liegenden Geräts verweisen.
[in] MinorFunction
Gibt einen der folgenden IRP-Codes für Nebenleistung an: IRP_MN_QUERY_POWER, IRP_MN_SET_POWER oder IRP_MN_WAIT_WAKE.
[in] PowerState
Gibt einen POWER_STATE Wert an, der im IRP übergeben werden soll. Geben Sie für IRP_MN_SET_POWER und IRP_MN_QUERY_POWER den angeforderten neuen Gerätestromzustand an. Mögliche Werte sind DEVICE_POWER_STATE Werte.
Geben Sie für IRP_MN_WAIT_WAKE den niedrigsten Systemstromzustand (mit der geringsten Stromversorgung) an, aus dem das Gerät das System reaktivieren darf. Mögliche Werte sind SYSTEM_POWER_STATE Werte.
[in, optional] CompletionFunction
Ein Zeiger auf die PowerCompletion-Rückrufroutine des Aufrufers. Der E/A-Manager ruft diese Routine auf, wenn die IRP abgeschlossen ist. Dieser Parameter ist optional und kann auf NULL festgelegt werden, wenn keine PowerCompletion-Rückrufroutine erforderlich ist.
[in, optional] Context
Ein Zeiger auf einen vom Aufrufer bereitgestellten Kontext, der an den PowerCompletion-Rückruf übergeben werden soll. Wenn der Aufrufer als Reaktion auf eine IRP für den Systemsatz eine IRP für Gerätesatzleistung anfordert, sollte der Kontext die IRP des Systemset-Power-IRP enthalten, die die Anforderung ausgelöst hat.
[out] Irp
Ein Zeiger auf eine vom Aufrufer bereitgestellte Variable, in der PoRequestPowerIrp einen Zeiger auf den IRP zurückgibt, den es ordnet. Geben Sie nur einen Wert für Irp an, wenn der MinorFunction-Parameter auf IRP_MN_WAIT_WAKE festgelegt ist. Andernfalls sollte dieser Parameter immer NULL sein, da der IRP möglicherweise abgeschlossen ist, bevor PoRequestPowerIrp zurückgibt, wodurch dieser Parameter auf den bereits verworfenen Arbeitsspeicher verweist.
Rückgabewert
PoRequestPowerIrp gibt eine der folgenden Rückgaben zurück:
| Rückgabecode | Beschreibung |
|---|---|
|
Die IRP wurde gesendet. |
|
Die Routine konnte die IRP nicht zuordnen. |
|
MinorFunction bedeutet keinen gültigen IRP-Code für neben der Leistung. |
Hinweise
Ein Besitzer einer Geräteenergierichtlinie ruft diese Routine auf, um eine Warte-/Aktivierungs-, Abfrage- oder Set-Power-IRP zu senden.
Ein Treiber ruft PoRequestPowerIrp (nicht IoAllocateIrp) auf, um eine Leistungs-IRP zuzuweisen und zu senden, die über geringfügigen IRP-Code IRP_MN_SET_POWER, IRP_MN_QUERY_POWER oder IRP_MN_WAIT_WAKE verfügt. (Ein Treiber muss IoAllocateIrp aufrufen, um eine Energie-IRP mit untergeordnetem IRP-Code IRP_MN_POWER_SEQUENCE zu senden.)
Wenn PoRequestPowerIrp einen status Wert von STATUS_PENDING zurückgibt, hat die Routine erfolgreich einen Geräteleistungs-IRP zugewiesen und an den oberen Rand des Gerätestapels für das Gerät gesendet. Nachdem der Bustreiber und alle anderen Treiber die IRP abgeschlossen haben und der E/A-Manager alle IoCompletion-Routinen aufgerufen hat, die von Treibern festgelegt wurden, während sie den IRP im Gerätestapel übergeben haben, ruft der E/A-Manager die PowerCompletion-Routine auf und übergibt an diese Routine den angegebenen Context-Wert . Wenn PoRequestPowerIrp einen anderen status als STATUS_PENDING zurückgibt, hat die Routine kein Geräteleistungs-IRP gesendet, und die PowerCompletion-Routine wird nicht aufgerufen.
Die PowerCompletion-Routine führt alle zusätzlichen Aufgaben aus, die der Absender des IRP benötigt, nachdem alle anderen Treiber die IRP abgeschlossen haben. Die IRP muss nicht frei sein; Der Power-Manager tut dies. In Windows 2000 und höheren Versionen von Windows kann die PowerCompletion-Routine unter IRQL = PASSIVE_LEVEL oder IRQL = DISPATCH_LEVEL aufgerufen werden. In Windows 98/Me wird die PowerCompletion-Routine immer unter IRQL = PASSIVE_LEVEL aufgerufen, und Treiber müssen IRPs unter IRQL = PASSIVE_LEVEL abschließen.
Ein Besitzer der Geräteenergierichtlinie ruft PoRequestPowerIrp auf, um eine Geräteabfrage- oder Set-Power-IRP zu senden, wenn er eine Systemabfrage- oder Set-Power-IRP empfängt. Der Treiber sollte eine IoCompletion-Routine in der System-IRP festlegen und die System-IRP an den nächstniedrigten Treiber übergeben. Die IoCompletion-Routine ruft PoRequestPowerIrp auf, um das Geräte-IRP zu senden, wobei die System-IRP im Context-Parameter übergeben wird. Der Context-Parameter wird anschließend an die PowerCompletion-Routine für das Geräte-IRP übergeben. In der PowerCompletion-Routine kann der Treiber die System-IRP abschließen. Weitere Informationen finden Sie unter Senden von IRP_MN_QUERY_POWER oder IRP_MN_SET_POWER für Gerätestromzustände und Rückrufroutinen mit Warte-/Reaktivierung.
Treiber können den zurückgegebenen Irp verwenden, um eine IRP_MN_WAIT_WAKE IRP abzubrechen. Treiber, die andere Arten von Power IRPs anfordern, müssen NULL für diesen Parameter übergeben.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Verfügbar ab Windows 2000. |
| Zielplattform | Universell |
| Header | wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h) |
| Bibliothek | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |
| DDI-Complianceregeln | HwStorPortProhibitedDIs(storport), MarkDevicePower(wdm), PowerDownFail(wdm), PowerUpFail(wdm), RequestedPowerIrp(wdm) |