PoRequestPowerIrp 函式 (wdm.h)

發行項
02/29/2024

PoRequestPowerIrp 例程會配置電源 IRP，並將它傳送至指定裝置裝置堆疊中的頂端驅動程式。

語法

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
);

參數

[in] DeviceObject

IRP 目標 DEVICE_OBJECT 指標。在 Windows 2000 和更新版本的 Windows 中，此參數可以指向實體裝置物件， (PDO) 或功能裝置物件 (FDO) 。在 Windows 98/Me 中，此參數必須指向基礎裝置的 PDO。

[in] MinorFunction

指定下列其中一個次要電源 IRP 代碼： IRP_MN_QUERY_POWER、 IRP_MN_SET_POWER或 IRP_MN_WAIT_WAKE。

[in] PowerState

指定要傳入 IRP 的POWER_STATE 值。針對 IRP_MN_SET_POWER 和 IRP_MN_QUERY_POWER，請指定要求的新裝置電源狀態。可能的值為 DEVICE_POWER_STATE 值。

針對 IRP_MN_WAIT_WAKE，指定允許裝置喚醒系統的最低 (最低電源 ) 系統電源狀態。可能的值為 SYSTEM_POWER_STATE 值。

[in, optional] CompletionFunction

呼叫端 PowerCompletion 回呼例程的指標。 I/O 管理員會在 IRP 完成時呼叫此例程。如果不需要 PowerCompletion 回呼例程，此參數是選擇性的，而且可以設定為 NULL。

[in, optional] Context

要傳遞至 PowerCompletion 回呼之呼叫端提供內容的指標。當呼叫端要求裝置設定電源 IRP 以響應系統設定電源 IRP 時， Context 應該包含觸發要求的系統設定電源 IRP。

[out] Irp

呼叫端提供之變數的指標，其中 PoRequestPowerIrp 會傳回其配置之 IRP 的指標。只有在 MinorFunction 參數設定為 IRP_MN_WAIT_WAKE 時，才指定 Irp 的值。否則，這個參數應該一律為 NULL ，因為 PoRequestPowerIrp 傳 回之前可能會完成 IRP，導致此參數指向已經捨棄的記憶體。

傳回值

PoRequestPowerIrp 會 傳回下列其中一項：

傳回碼	Description
STATUS_PENDING	IRP 已傳送。
STATUS_INSUFFICIENT_RESOURCES	例程無法配置 IRP。
STATUS_INVALID_PARAMETER_2	MinorFunction 不會表示有效的次要電源 IRP 程序代碼。

備註

裝置電源原則擁有者會呼叫此例程來傳送等候/喚醒、查詢或設定電源 IRP。

驅動程式會呼叫 PoRequestPowerIrp，而不是 IoAllocateIrp，以配置並傳送具有次要 IRP 程式代碼的電源 IRP IRP_MN_SET_POWER、 IRP_MN_QUERY_POWER或 IRP_MN_WAIT_WAKE。 (驅動程式必須呼叫 IoAllocateIrp ，以使用次要IRP程式代碼傳送電源IRP IRP_MN_POWER_SEQUENCE.)

如果 PoRequestPowerIrp 傳回狀態值STATUS_PENDING，則例程已成功配置裝置電源 IRP，並將它傳送至裝置的裝置堆疊頂端。在總線驅動程式和所有其他驅動程式完成 IRP 之後，I/O 管理員已呼叫驅動程式在裝置堆疊中傳遞 IRP 時所設定的所有 IoCompletion 例程，I/O 管理員會呼叫 PowerCompletion 例程，並傳遞至此例程指定的 Context 值。如果 PoRequestPowerIrp 傳回STATUS_PENDING以外的狀態，則例程不會傳送裝置電源 IRP，而且不會呼叫 PowerCompletion 例程。

PowerCompletion 例程會在所有其他驅動程式完成 IRP 之後，執行 IRP 傳送者所需的任何其他工作。它不需要釋放 IRP;電源管理員會執行此作業。在 Windows 2000 和更新版本的 Windows 中， PowerCompletion 例程可以在 IRQL = PASSIVE_LEVEL或 IRQL = DISPATCH_LEVEL呼叫。在 Windows 98/Me 中， PowerCompletion 例程一律會在 IRQL = PASSIVE_LEVEL呼叫，而且驅動程式必須在 IRQL = PASSIVE_LEVEL完成 IRP。

當裝置電源原則擁有者收到系統查詢或設定電源 IRP 時，會呼叫 PoRequestPowerIrp 來傳送裝置查詢或設定電源 IRP。驅動程式應該會在系統 IRP 中設定 IoCompletion 例程，並將系統 IRP 傳遞至下一個較低的驅動程式。 IoCompletion 例程會呼叫 PoRequestPowerIrp 來傳送裝置 IRP，並在 Context 參數中傳遞系統 IRP。 Context 參數隨後會傳遞至裝置 IRP 的 PowerCompletion 例程。在 PowerCompletion 例程中，驅動程式可以完成系統 IRP。如需詳細資訊，請參閱傳送裝置電源狀態的IRP_MN_QUERY_POWER或IRP_MN_SET_POWER 和等候/喚醒回呼例程。

驅動程式可以使用傳回的 Irp 來取消 IRP_MN_WAIT_WAKE IRP。要求其他類型的電源 IRP 的驅動程式必須針對此參數傳遞 NULL 。

規格需求

需求	值
最低支援的用戶端	從 Windows 2000 開始提供。
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
DDI 合規性規則	HwStorPortProhibitedDIs (storport) 、 MarkDevicePower (wdm ) 、 PowerDownFail (wdm) 、 PowerUpFail (wdm) 、 RequestedPowerIrp (wdm)