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 时, 上下文 应包含触发请求的系统集电源 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_POWERIRP_MN_QUERY_POWERIRP_MN_WAIT_WAKE的电源 IRP。 (驱动程序必须调用 IoAllocateIrp ,才能使用次要 IRP 代码 IRP_MN_POWER_SEQUENCE.) 发送电源 IRP

如果 PoRequestPowerIrp 返回状态值STATUS_PENDING,则例程已成功分配设备电源 IRP 并将其发送到设备的设备堆栈顶部。 在总线驱动程序和所有其他驱动程序完成 IRP 后,I/O 管理器调用驱动程序在设备堆栈中传递 IRP 时设置的所有 IoCompletion 例程,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。

设备电源策略所有者调用 PoRequestPowerIrp ,以在收到系统查询或设置电源 IRP 时发送设备查询或设置电源 IRP。 驱动程序应在系统 IRP 中设置 IoCompletion 例程,并将系统 IRP 传递给下一个较低驱动程序。 IoCompletion 例程调用 PoRequestPowerIrp 发送设备 IRP,并在 Context 参数中传递系统 IRP。 上下文参数随后将传递给设备 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 符合性规则 HwStorPortProhibitedDDIS (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