PoRequestPowerIrp 函数 (wdm.h)

项目
08/08/2023

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 返回下列值之一：

返回代码	说明
STATUS_PENDING	IRP 已发送。
STATUS_INSUFFICIENT_RESOURCES	例程无法分配 IRP。
STATUS_INVALID_PARAMETER_2	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)