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 时， 上下文 应包含触发请求的系统集电源 IRP。
[out] Irp
指向调用方提供的变量的指针， PoRequestPowerIrp 在其中返回指向它分配的 IRP 的指针。 仅当 MinorFunction 参数设置为 IRP_MN_WAIT_WAKE 时，才为 Irp 指定值。 否则，此参数应始终为 NULL ，因为 IRP 可能在 PoRequestPowerIrp 返回之前完成，从而导致此参数指向已放弃的内存。
返回值
PoRequestPowerIrp 返回下列值之一：
| 返回代码 | 说明 |
|---|---|
|
IRP 已发送。 |
|
例程无法分配 IRP。 |
|
MinorFunction 不表示有效的次要电源 IRP 代码。 |
注解
设备电源策略所有者调用此例程来发送等待/唤醒、查询或设置电源 IRP。
驱动程序调用 PoRequestPowerIrp（而不是 IoAllocateIrp）来分配和发送具有次要 IRP 代码 IRP_MN_SET_POWER、 IRP_MN_QUERY_POWER或IRP_MN_WAIT_WAKE的电源 IRP。 (驱动程序必须调用 IoAllocateIrp 以发送具有次要 IRP 代码 的电源 IRP IRP_MN_POWER_SEQUENCE.)
如果 PoRequestPowerIrp 返回状态值STATUS_PENDING，则例程已成功分配设备电源 IRP，并将其发送到设备堆栈的顶部。 在总线驱动程序和所有其他驱动程序完成 IRP 后，I/O 管理器调用驱动程序设置的所有 IoCompletion 例程，因为他们将 IRP 向下传递设备堆栈，I/O 管理器调用 PowerCompletion 例程，并将指定的 上下文 值传递给此例程。 如果 PoRequestPowerIrp 返回STATUS_PENDING以外的状态，则例程未发送设备电源 IRP，并且不会调用 PowerCompletion 例程。
PowerCompletion 例程在所有其他驱动程序完成 IRP 后执行 IRP 的发送方所需的任何其他任务。 它不需要释放 IRP;电源管理器会这样做。 在 Windows 2000 及更高版本的 Windows 中，可以在 IRQL = PASSIVE_LEVEL 或 IRQL = DISPATCH_LEVEL 调用 PowerCompletion 例程。 在 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 开始可用。 |
| 目标平台 | 通用 |
| 标头 | wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h） |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |
| DDI 符合性规则 | HwStorPortProhibitedDDI (storport) 、 MarkDevicePower (wdm) 、 PowerDownFail (wdm) 、 PowerUpFail (wdm) 、 RequestedPowerIrp (wdm) |