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_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 |
|---|---|
|
IRP 已傳送。 |
|
例程無法配置 IRP。 |
|
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) |