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

Статья
03/08/2023

Подпрограмма ExRegisterCallback регистрирует заданную подпрограмму обратного вызова с заданным объектом обратного вызова.

Синтаксис

PVOID ExRegisterCallback(
  [in, out]      PCALLBACK_OBJECT   CallbackObject,
  [in]           PCALLBACK_FUNCTION CallbackFunction,
  [in, optional] PVOID              CallbackContext
);

Параметры

[in, out] CallbackObject

Указатель на объект обратного вызова, полученный из подпрограммы ExCreateCallback .

[in] CallbackFunction

Указатель на процедуру обратного вызова, реализованную драйвером, которая должна быть непередающейся. Подпрограмма обратного вызова должна соответствовать следующему прототипу:

VOID
(*PCALLBACK_FUNCTION ) (
    IN PVOID CallbackContext,
    IN PVOID Argument1,
    IN PVOID Argument2
    );

Ниже приведены параметры подпрограммы обратного вызова.

CallbackContext

Указатель на область контекста, предоставленную драйвером, как указано в параметре CallbackContextобъекта ExRegisterCallback.

Аргумент1

Указатель на параметр, определенный объектом обратного вызова.

Аргумент2

Указатель на параметр, определенный объектом обратного вызова.

[in, optional] CallbackContext

Указатель на определяемую вызывающим объектом структуру элементов данных, передаваемых в качестве контекстного параметра подпрограммы обратного вызова при каждом вызове. Обычно контекст является частью расширения объекта устройства вызывающего объекта.

Возвращаемое значение

ExRegisterCallback возвращает указатель на дескриптор регистрации обратного вызова, который следует рассматривать как непрозрачный и зарезервированный для использования системой. Этот указатель имеет значение NULL , если ExRegisterCallback завершается ошибкой.

Если объект допускает только одну зарегистрированную подпрограмму обратного вызова и такая подпрограмма уже зарегистрирована, ExRegisterCallback возвращает значение NULL.

Вызывающие методы ExRegisterCallback должны сохранить возвращенный указатель для последующего использования в вызове ExUnregisterCallback. Указатель необходим при удалении подпрограммы обратного вызова из списка зарегистрированных процедур обратного вызова для объекта обратного вызова.

Значения аргументов Argument1 и Argument2 зарегистрированной подпрограммы обратного вызова зависят от объекта обратного вызова и определяются компонентом, который его создал. Ниже приведены параметры для системных объектов обратного вызова.

\Callback\SetSystemTime

Argument1 (SetSystemTime)

Не используется.

Argument2 (SetSystemTime)

Не используется.

\Callback\PowerState**

Argument1 (PowerState)

Значение константы PO_CB_XXX, приведение к типу PVOID.
PO_CB_AC_STATUS — указывает, что система изменила питание от аккумулятора или наоборот.
PO_CB_LID_SWITCH_STATE — указывает, что переключатель крышки изменил состояния.
PO_CB_PROCESSOR_POWER_POLICY — указывает, что политика питания системного процессора изменилась.
PO_CB_SYSTEM_POWER_POLICY — указывает, что политика управления питанием системы изменилась.
PO_CB_SYSTEM_STATE_LOCK — указывает, что изменение состояния питания системы неминуемо. Драйверы в пути разбиения по страницам могут регистрироваться для этого обратного вызова, чтобы получать раннее предупреждение о таком изменении, что позволяет им заблокировать код в памяти до изменения состояния питания.

Argument2 (PowerState)

Значение TRUE или FALSE , приведение к типу PVOID.

Если аргумент Argument1 имеет PO_CB_AC_STATUS, аргумент 2 имеет значение TRUE , если компьютер в настоящее время использует источник питания A/C, и false , если компьютер работает от батареи.
Если Аргумент1 имеет PO_CB_LID_SWITCH_STATE, аргумент 2 имеет значение TRUE , если крышка открыта в данный момент, и значение FALSE , если крышка закрыта.
Если аргумент 1 PO_CB_PROCESSOR_POWER_POLICY, Аргумент 2 не используется.
Если аргумент Argument1 PO_CB_SYSTEM_POWER_POLICY, Аргумент 2 не используется.
Если Аргумент1 имеет значение PO_CB_SYSTEM_STATE_LOCK, аргумент 2 имеет значение FALSE , если компьютер вот-вот выйдет из состояния питания системы S0, и имеет значение TRUE , если компьютер только что перешел в S0.

\Callback\ProcessorAdd

Argument1 (ProcessorAdd)

Указатель на структуру KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT , описывающую событие уведомления об изменении обработчика. Этот указатель приводится к типу PVOID. Подпрограмма обратного вызова не должна изменять содержимое этой структуры.

Argument2 (ProcessorAdd)

Указатель на переменную, содержащую значение NTSTATUS. Этот указатель приводится к типу PVOID. При определенных условиях подпрограмма обратного вызова может записать в эту переменную значение состояния ошибки, чтобы указать, почему не следует добавлять новый процессор. Драйвер устройства не должен изменять значение этой переменной, если не выполняются все три из следующих условий:

Во время обработки процедуры обратного вызова возникает ошибка, которая должна препятствовать добавлению нового процессора.
Значение элемента State структуры KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT , на которую указывает Argument1 , равно KeProcessorAddStartNotify.
Переменная NSTATUS, на которую указывает Argument2 , содержит значение STATUS_SUCCESS. То есть подпрограмма обратного вызова не должна перезаписывать значение состояния ошибки, которое ранее было записано другим клиентом уведомления о обратном вызове.

Начиная с Windows Vista объект обратного вызова \Callback\ProcessorAdd доступен для динамического отслеживания изменений в генеральной совокупности процессора. Подпрограмма KeRegisterProcessorChangeCallback предоставляет аналогичные сведения, но также поддерживает флаг KE_PROCESSOR_CHANGE_ADD_EXISTING, который драйвер может использовать для перечисления процессоров в начальной конфигурации многопроцессорной системы. Для драйверов, работающих в Windows Server 2008 и более поздних версиях Windows, используйте KeRegisterProcessorChangeCallback вместо объекта обратного вызова \Callback\ProcessorAdd , если это возможно.

Дополнительные сведения об объектах обратного вызова см. в разделе Объекты обратного вызова.

Операционная система вызывает зарегистрированные подпрограммы обратного вызова в том же IRQL, в котором драйвер, создавший обратный вызов, вызывал подпрограмму ExNotifyCallback .

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDDIs(storport), IrqlExApcLte2(wdm)