wdm.h) (PoRegisterPowerSettingCallback 函数
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
电源管理器用于表示回调例程的句柄。 驱动程序随后必须在调用 PoUnregisterPowerSettingCallback 时提供此句柄,以取消注册回调例程。
返回值
PoRegisterPowerSettingCallback 返回下列值之一:
返回代码 | 说明 |
---|---|
STATUS_SUCCESS | 该例程注册了回调例程。 |
STATUS_INSUFFICIENT_RESOURCES | 例程无法分配注册回调例程所需的系统资源。 |
注解
驱动程序调用 PoRegisterPowerSettingCallback 向电源管理器注册回调例程。 电源管理器随后调用此回调例程,以便在指定的电源设置发生更改后通知驱动程序。 此外,电源管理器通过立即调用回调例程并传递电源设置的当前值来初始化驱动程序的电源设置。 无论电源设置是否已实际更改,电源管理器都以这种方式初始化驱动程序的电源设置。
驱动程序应针对驱动程序需要监视的每个电源设置调用 PoRegisterPowerSettingCallback 。 驱动程序应在初始化期间在其 DriverEntry 例程中调用此例程。 通常,大多数驱动程序在 Context 参数中传递指向设备扩展的指针。
若要取消注册电源设置回调,请调用 PoUnregisterPowerSettingCallback 例程。
通常,Kernel-Mode 驱动程序框架 (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 回调
电源设置回调例程的函数原型如下所示:
NTSTATUS
POWER_SETTING_CALLBACK (
_In_ LPCGUID SettingGuid,
_In_ PVOID Value,
_In_ ULONG ValueLength,
_Inout_opt_ PVOID Context
);
电源设置回调参数为:
SettingGuid
指向 GUID 的指针,该 GUID 表示已更改的电源设置。 电源设置及其相应的 GUID 在 Wdm.h 中定义。
值
指向已更改的电源设置的新值的指针。
ValueLength
ULONG 类型的值,该值指定新电源设置值的大小(以字节为单位)。
上下文
指向驱动程序在调用注册回调例程的 PoRegisterPowerSettingCallback 中提供的上下文的指针。
电源管理器在 IRQL = PASSIVE_LEVEL 调用电源设置回调。
示例
若要定义电源设置回调例程,必须首先提供一个函数声明,用于标识要定义的回调函数的类型。 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_
,请参阅 批注函数行为。
要求
要求 | 值 |
---|---|
目标平台 | 通用 |
标头 | wdm.h(包括 Wdm.h、Ntddk.h、Ntifs.h) |
Library | NtosKrnl.lib |
DLL | NtosKrnl.exe |
IRQL | PASSIVE_LEVEL (请参阅“备注”部分) |