共用方式為


PoRequestPowerIrp 函式 (wdm.h)

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_POWERIRP_MN_SET_POWERIRP_MN_WAIT_WAKE

[in] PowerState

指定要傳入 IRP 的POWER_STATE 值。 針對 IRP_MN_SET_POWERIRP_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_POWERIRP_MN_QUERY_POWERIRP_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)

另請參閱

IO_STATUS_BLOCK

IRP

IRP_MN_POWER_SEQUENCE

IRP_MN_QUERY_POWER

IRP_MN_SET_POWER

IRP_MN_WAIT_WAKE

IoAllocateIrp

PoStartNextPowerIrp

PowerCompletion