PO_FX_COMPONENT_IDLE_STATE_CALLBACK回调函数 (wdm.h)

项目
03/08/2023

ComponentIdleStateCallback 回调例程通知驱动程序对指定组件的 Fx 电源状态的挂起更改。

语法

PO_FX_COMPONENT_IDLE_STATE_CALLBACK PoFxComponentIdleStateCallback;

void PoFxComponentIdleStateCallback(
  [in] PVOID Context,
  [in] ULONG Component,
  [in] ULONG State
)
{...}

参数

[in] Context

指向设备上下文的指针。设备驱动程序使用此上下文来存储有关设备当前电源状态的信息。设备驱动程序在PO_FX_DEVICE结构的 DeviceContext 成员中指定了此指针，驱动程序用于将设备注册到电源管理框架 (PoFx) 。此上下文对 PoFx 是不透明的。

[in] Component

指定组件编号。此参数是设备驱动程序用于将设备注册到 PoFx 的 PO_FX_DEVICE 结构中的 Components 数组的索引。如果 Components 数组包含 N 个元素，则组件索引的范围为 0 到 N-1。

[in] State

指定组件将更改为的新 Fx 电源状态。如果此参数为零，则新状态为 F0;如果此参数为 1，则新状态为 F1;等等。

返回值

无

备注

当 PoFx 调用驱动程序的 ComponentIdleStateCallback 例程时，驱动程序可能需要为挂起的 Fx 状态更改做好准备。完成任何必要的准备后，驱动程序必须调用 PoFxCompleteIdleState 例程，以通知 PoFx 驱动程序已完成对 ComponentIdleStateCallback 回调的响应。 PoFxCompleteIdleState 调用可以在 ComponentIdleStateCallback 例程返回之前或之后发生。

如果组件要从 F0 切换到设备将丢失组件的硬件状态的低功耗 Fx 状态，则驱动程序必须在转换到新的 Fx 状态之前保存组件的硬件状态。如果组件要从低功率 Fx 状态切换到 F0，并且之前保存了硬件状态，则驱动程序应在将电源还原到组件后还原硬件状态。

对于某些设备，组件电源状态可能在设备硬件中控制。对于这些设备，驱动程序通常负责更改组件的电源状态。对于其他设备，组件的电源状态可能由设备外部的硬件控制，驱动程序通常必须依赖 PoFx 来配置组件的电源状态。

如果驱动程序负责配置组件的电源状态，则驱动程序应更改电源状态以响应 ComponentIdleStateCallback 回调。若要从 F0 转换为低功率 Fx 状态，组件在进入 ComponentIdleStateCallback 例程时处于 F0 中，驱动程序必须在调用 PoFxCompleteIdleState 之前将组件切换为新的 Fx 状态。对于从低功率 Fx 状态到 F0 的转换，组件在进入 ComponentIdleStateCallback 例程时处于低功率 Fx 状态，驱动程序必须在调用 PoFxCompleteIdleState 之前将组件切换到 F0。

如果驱动程序不负责配置组件的电源状态，则驱动程序应假定组件在进入 ComponentIdleStateCallback 例程时始终处于 F0 状态。对于从 F0 到低功率 Fx 状态的挂起转换，直到驱动程序调用 PoFxCompleteIdleState 之后才会转换到新的 Fx 状态。对于从低功率 Fx 状态到 F0 的转换，在调用 ComponentIdleStateCallback 例程之前，将转换到 F0。

PoFx 从不调用 ComponentIdleStateCallback 例程直接从一个低功率 Fx 状态切换到另一个低功率 Fx 状态。例如，PoFx 可能需要将组件从一个低功率 Fx 状态切换到另一个，以响应对 PoFxSetComponentLatency、 PoFxSetComponentResidency 或 PoFxSetComponentWake 例程的调用。在这种情况下，PoFx 首先调用 ComponentIdleStateCallback 例程以从旧的 Fx 状态切换到 F0，然后再次调用 ComponentIdleStateCallback 例程以从 F0 切换到新的 Fx 状态。

示例

若要定义 ComponentIdleStateCallback 回调例程，必须首先提供一个函数声明，用于标识要定义的回调例程的类型。 Windows 为驱动程序提供一组回调函数类型。使用回调函数类型声明函数有助于驱动程序代码分析、静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，并且这是编写适用于 Windows 操作系统的驱动程序的要求。

例如，若要定义名为 MyComponentIdleStateCallback的 ComponentIdleStateCallback 回调例程，请使用PO_FX_COMPONENT_IDLE_STATE_CALLBACK类型，如以下代码示例所示：

PO_FX_COMPONENT_IDLE_STATE_CALLBACK MyComponentIdleStateCallback;

然后，按如下所示实现回调例程：

_Use_decl_annotations_
VOID
  MyComponentIdleStateCallback(
    PVOID Context,
    ULONG Component,
    ULONG State
    )
  {
      // Function body
  }

PO_FX_COMPONENT_IDLE_STATE_CALLBACK函数类型在 Wdm.h 头文件中定义。若要在运行代码分析工具时更准确地识别错误，请务必将 _Use_decl_annotations_ 注释添加到函数定义。注释 _Use_decl_annotations_ 可确保使用应用于头文件中PO_FX_COMPONENT_IDLE_STATE_CALLBACK函数类型的注释。有关函数声明要求的详细信息，请参阅使用 WDM 驱动程序的函数角色类型声明函数。有关的信息 _Use_decl_annotations_，请参阅批注函数行为。

要求

要求	值
最低受支持的客户端	在 Windows 8 及更高版本的 Windows 中受支持。
目标平台	桌面
标头	wdm.h (包括 Wudfwdm.h)
IRQL	在 IRQL <= DISPATCH_LEVEL 调用。