poFxRegisterDevice 函数 (wdm.h)
PoFxRegisterDevice 例程将设备注册到电源管理框架 (PoFx) 。
语法
NTSTATUS PoFxRegisterDevice(
[in] PDEVICE_OBJECT Pdo,
[in] PPO_FX_DEVICE Device,
[out] POHANDLE *Handle
);
参数
[in] Pdo
指向 物理设备对象的 指针 (PDO) 。 此参数指向表示正在注册的物理设备的 DEVICE_OBJECT 结构。 调用方是设备的电源策略所有者，通常是设备的函数驱动程序。
[in] Device
指向调用方分配 的PO_FX_DEVICE 结构的指针，该结构包含设备的注册信息。 此结构包含指向设备驱动程序实现的一组回调例程的指针。 PoFx 调用这些例程来与驱动程序通信。
[out] Handle
指向例程在其中写入句柄的位置的指针，该句柄表示设备向 PoFx 注册。 设备驱动程序将此句柄作为输入参数传递给它调用的其他 PoFxXxx 例程。 驱动程序必须先调用 PoFxRegisterDevice 来注册设备，然后驱动程序才能调用任何其他 PoFxXxx 例程来管理设备。
返回值
如果例程成功注册设备，则 PoFxRegisterDevice 将返回STATUS_SUCCESS。 可能的错误返回值包括以下状态代码。
| 返回代码 | 说明 |
|---|---|
|
Pdo 为 NULL;或 PPO_FX_DEVICE 结构的版本号无效或组件计数为零;或为组件指定的空闲状态数为零;或空闲状态的说明无效。 |
|
设备未准备就绪。 |
|
可用资源不足，无法完成注册。 |
注解
设备驱动程序通常从驱动程序的 IRP_MN_START_DEVICE 请求处理程序调用此例程。 在设备收到 IRP_MN_START_DEVICE 请求之前，驱动程序不得调用此例程。 首次启动设备时，设备会收到第一个 IRP_MN_START_DEVICE 请求。 在停止资源均衡后，每次重启设备时，设备都会收到额外的 IRP_MN_START_DEVICE 请求。 用于注册已注册设备的 PoFxRegisterDevice 调用是一个严重错误，会导致检查 bug。 请注意，PoFx 会将设备结构深层复制到其内存中。
在驱动程序调用 PoFxRegisterDevice 之前，设备必须满足以下条件：
- 设备 (即 PDO) 尚未注册到 PoFx。
- 设备处于 D0 (完全处于) 电源状态。
- 设备处于运行状态。
- 设备中的每个组件都处于 F0 (完全处于) 电源状态。
- 每个组件都处于活动状态。
驱动程序调用 PoFxRegisterDevice 将设备注册到 PoFx 后，设备中的所有组件都处于完全打开状态并处于活动状态，以便驱动程序可以完成硬件初始化。 若要启动活动电源管理，驱动程序必须调用 PoFxStartDevicePowerManagement 例程。
默认情况下， PoFxStartDevicePowerManagement 将所有组件切换到空闲条件。 如果驱动程序要求组件在电源管理启动后立即处于活动状态，则驱动程序必须通过调用 PoFxActivateComponent 例程显式激活该组件，并且此调用必须在 PoFxRegisterDevice 调用之后、 PoFxStartDevicePowerManagement 调用之前发生。
通常，单组件设备的 Kernel-Mode 驱动程序框架 (KMDF) 驱动程序不会调用 PoFxRegisterDevice 将设备注册到 PoFx。 相反，当 KMDF 调用驱动程序的 EvtDeviceWdmPostPoFxRegisterDevice 回调函数时，此驱动程序会收到 PoFx 注册句柄。 有关详细信息，请参阅 支持 Single-Component 设备的多个功能电源状态。
有关多组件设备的 KMDF 驱动程序如何注册到 PoFx 的信息，请参阅 支持 Multiple-Component 设备的多个功能电源状态。
要求
| 最低受支持的客户端 | 从 Windows 8 开始可用。 |
| 目标平台 | 通用 |
| 标头 | wdm.h |
| Library | Ntoskrnl.lib |
| DLL | Ntoskrnl.exe |
| IRQL | PASSIVE_LEVEL |