PoRequestPowerIrp-Funktion (wdm.h)

Artikel
08/08/2023

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
STATUS_PENDING	Die IRP wurde gesendet.
STATUS_INSUFFICIENT_RESOURCES	Die Routine konnte die IRP nicht zuordnen.
STATUS_INVALID_PARAMETER_2	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)