Функция PoRegisterPowerSettingCallback (ntifs.h)
Подпрограмма PoRegisterPowerSettingCallback регистрирует подпрограмму обратного вызова power setting для получения уведомлений об изменениях в указанном параметре питания.
Синтаксис
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, представляющий параметр питания для этой регистрации. При изменении указанного параметра питания диспетчер управления питанием вызывает подпрограмму обратного вызова, чтобы уведомить драйвер об изменении и указать новое значение параметра. Дополнительные сведения см. в подразделе "Примечания".
[in] Callback
Указатель на процедуру обратного вызова для настройки питания, реализованную вызывающим объектом, которая вызывается диспетчером питания при изменении указанного параметра питания. Функциональный прототип процедуры обратного вызова см. в разделе Power-Setting Callback ниже.
[in, optional] Context
Указатель на контекст для подпрограммы обратного вызова. Этот параметр является необязательным. Он предоставляется для передачи контекста драйвера или устройства в подпрограмму обратного вызова. Если этот параметр не используется, ему необходимо задать значение NULL.
[out] Handle
Дескриптор, который диспетчер управления питанием использует для представления подпрограммы обратного вызова. Драйвер должен впоследствии предоставить этот дескриптор в вызове PoUnregisterPowerSettingCallback , чтобы отменить регистрацию процедуры обратного вызова.
Возвращаемое значение
PoRegisterPowerSettingCallback возвращает одно из следующих элементов:
| Код возврата | Описание |
|---|---|
| STATUS_SUCCESS | Подпрограмма зарегистрировала подпрограмму обратного вызова. |
| STATUS_ INSUFFICIENT_RESOURCES | Подпрограмме не удалось выделить системные ресурсы, необходимые для регистрации процедуры обратного вызова. |
Комментарии
Драйвер вызывает PoRegisterPowerSettingCallback , чтобы зарегистрировать подпрограмму обратного вызова в диспетчере питания. Диспетчер питания впоследствии вызывает эту процедуру обратного вызова, чтобы уведомить водителя об изменении указанного параметра питания. Кроме того, диспетчер питания инициализирует параметр питания драйвера, немедленно вызывая подпрограмму обратного вызова и передавая текущее значение параметра питания. Диспетчер питания инициализирует параметр питания драйвера таким образом независимо от того, действительно ли изменился параметр питания.
Драйвер должен вызывать PoRegisterPowerSettingCallback для каждого параметра питания, который должен отслеживать драйвер. Драйверы должны вызывать эту подпрограмму в своей подпрограмме DriverEntry во время инициализации. Как правило, большинство драйверов передают указатель на расширение устройства в параметре Context .
Чтобы отменить регистрацию обратного вызова power setting, вызовите подпрограмму PoUnregisterPowerSettingCallback .
Как правило, драйверы Kernel-Mode Driver Framework (KMDF) должны вызывать PoRegisterPowerSettingCallback из функции обратного вызова EvtDeviceSelfManagedIoInit и вызывать PoUnregisterPowerSettingCallback из функции обратного вызова EvtDeviceSelfManagedIoCleanup . Эти драйверы не должны вызывать PoRegisterPowerSettingCallback из функции обратного вызова EvtDriverDeviceAdd ; В противном случае подпрограмма обратного вызова power-setting может быть вызвана до полной сборки стека драйверов.
Подпрограмма обратного вызова, зарегистрированная для определенного параметра питания, вызывается при переходе в состояние питания, при изменении значения параметра или при изменении диспетчером питания значения параметра. Например, если SettingGuid указывает на значение GUID GUID_LIDSWITCH_STATE_CHANGE, подпрограмма обратного вызова вызывается при нажатии крышки на ноутбуке. Параметр Value , переданный в подпрограмму обратного вызова в этом примере, указывает на значение ULONG, равное 1, если состояние переключателя крышки изменилось с закрытого на открытое, и равно 0, если состояние переключателя крышки изменилось с открытого на закрытое. Дополнительные сведения см. в определениях GUID power-setting и подробных комментариях в файле заголовка Wdm.h.
Первоначальный вызов подпрограммы обратного вызова может происходить непосредственно перед вызовом PoRegisterPowerSettingCallback , который регистрирует подпрограмму.
PoRegisterPowerSettingCallback можно вызывать только в irQL = PASSIVE_LEVEL.
Обратный вызов Power-Setting
Ниже приведен прототип функции процедуры обратного вызова 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 , который зарегистрировал подпрограмму обратного вызова. |
Примеры
Чтобы определить подпрограмму обратного вызова power-setting, необходимо сначала предоставить объявление функции, определяющее тип определяемой функции обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.
Например, чтобы определить подпрограмму обратного вызова power-setting с именем 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) |
| Библиотека | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (см. раздел "Примечания") |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по