PoRegisterPowerSettingCallback 函数 (ntifs.h)

项目
03/05/2024

PoRegisterPowerSettingCallback 例程注册电源设置回调例程，以接收指定电源设置中更改的通知。

语法

NTSTATUS PoRegisterPowerSettingCallback(
  [in, optional] PDEVICE_OBJECT          DeviceObject,
  [in]           LPCGUID                 SettingGuid,
  [in]           PPOWER_SETTING_CALLBACK Callback,
  [in, optional] PVOID                   Context,
  [out]          PVOID                   *Handle
);

参数

[in, optional] DeviceObject

指向与此例程的调用方关联的 DEVICE_OBJECT 结构的指针。此参数是可选的。它仅在内部用于调试目的。如果未提供此参数，则必须将其设置为 NULL。

[in] SettingGuid

指向 GUID 的指针，该 GUID 表示此注册的电源设置。当指定的电源设置发生更改时，电源管理器会调用回调例程，以通知驱动程序更改并提供设置的新值。有关详细信息，请参阅“备注”。

[in] Callback

指向调用方实现的电源设置回调例程的指针，当指定的电源设置更改时，电源管理器会调用该例程。有关回调例程的功能原型，请参阅下面的电源设置回调。

[in, optional] Context

指向回调例程上下文的指针。此参数是可选的。提供它以便可以将驱动程序或设备上下文传递给回调例程。如果未使用此参数，则必须将其设置为 NULL。

[out] Handle

Power Manager 用于表示回调例程的句柄。驱动程序随后必须在调用 PoUnregisterPowerSettingCallback 时提供此句柄，以取消注册回调例程。

返回值

PoRegisterPowerSettingCallback 返回下列值之一：

返回代码	说明
STATUS_SUCCESS	例程注册了回调例程。
STATUS_ INSUFFICIENT_RESOURCES	例程无法分配注册回调例程所需的系统资源。

注解

驱动程序调用 PoRegisterPowerSettingCallback 以向电源管理器注册回调例程。电源管理器随后调用此回调例程，以便在指定电源设置发生更改后通知驱动程序。此外，电源管理器通过立即调用回调例程并传递电源设置的当前值来初始化驱动程序的电源设置。无论电源设置是否实际更改，电源管理器都以这种方式初始化驱动程序的电源设置。

驱动程序应为驱动程序需要监视的每个电源设置调用 PoRegisterPowerSettingCallback 。驱动程序应在初始化期间在其 DriverEntry 例程中调用此例程。通常，大多数驱动程序在 Context 参数中传递指向设备扩展的指针。

若要取消注册电源设置回调，请调用 PoUnregisterPowerSettingCallback 例程。

通常，Kernel-Mode Driver Framework (KMDF) 驱动程序应从其 EvtDeviceSelfManagedIoInit 回调函数调用 PoRegisterPowerSettingCallback，并应从 EvtDeviceSelfManagedIoCleanup 回调函数调用 PoUnregisterPowerSettingCallback。这些驱动程序不应从其 EvtDriverDeviceAdd 回调函数调用 PoRegisterPowerSettingCallback;否则，可能会在完全生成驱动程序堆栈之前调用电源设置回调例程。

当电源状态转换发生更改设置的值时，或者当电源管理器更改设置的值时，将调用为特定电源设置注册的回调例程。例如，如果 SettingGuid 指向 GUID_LIDSWITCH_STATE_CHANGE GUID 值，则当笔记本电脑的盖子单击打开或关闭时，将调用回调例程。在此示例中传递给回调例程的 Value 参数指向 ULONG 值，如果盖开关的状态从关闭更改为打开，则为 1;如果盖开关的状态从打开更改为关闭，则为 0。有关详细信息，请参阅 Wdm.h 头文件中的电源设置 GUID 定义和大量注释。

在注册该例程的 PoRegisterPowerSettingCallback 调用返回之前，对回调例程的初始调用可能会立即发生。

只能在 IRQL = PASSIVE_LEVEL 调用 PoRegisterPowerSettingCallback。

Power-Setting 回调

电源设置回调例程的函数原型及其参数如下所示。电源管理器在 IRQL = PASSIVE_LEVEL 调用电源设置回调。

NTSTATUS
POWER_SETTING_CALLBACK (
  _In_ LPCGUID SettingGuid,
  _In_ PVOID Value,
  _In_ ULONG ValueLength,
  _Inout_opt_ PVOID Context
);

参数	说明
SettingGuid	指向表示已更改的电源设置的 GUID 的指针。电源设置及其相应的 GUID 在 Wdm.h 中定义。
值	指向已更改的电源设置的新值的指针。
ValueLength	ULONG 类型的值，指定新电源设置值的大小（以字节为单位）。
上下文	指向驱动程序在调用注册回调例程的 PoRegisterPowerSettingCallback 中提供的上下文的指针。

示例

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

例如，若要定义名为 MyPowerSettingCallback的电源设置回调例程，请使用 POWER_SETTING_CALLBACK 类型，如以下代码示例所示：

POWER_SETTING_CALLBACK MyPowerSettingCallback;

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

_Use_decl_annotations_
NTSTATUS
  MyPowerSettingCallback(
    LPCGUID SettingGuid,
    PVOID Value,
    ULONG ValueLength,
    PVOID Context 
    )
  {
      // Function body
  }

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

要求

要求	值
最低受支持的客户端	Windows Vista
目标平台	通用
标头	ntifs.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (请参阅备注部分)