Функция PoRegisterPowerSettingCallback (wdm.h)

Статья
03/08/2023

Подпрограмма 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.

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

Параметры обратного вызова power-setting:

SettingGuid
Указатель на GUID, представляющий измененный параметр питания. Параметры питания и соответствующие идентификаторы GUID определяются в Wdm.h.

Значение
Указатель на новое значение измененного параметра питания.

ValueLength
Значение типа ULONG, указывающее размер (в байтах) нового значения параметра питания.

Контекст
Указатель на контекст, предоставленный драйвером в вызове PoRegisterPowerSettingCallback , который зарегистрировал подпрограмму обратного вызова.

Диспетчер питания вызывает обратный вызов power-setting в IRQL = PASSIVE_LEVEL.

Примеры

Чтобы определить подпрограмму обратного вызова 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_см. в статье Поведение функции с заметками.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")