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

Статья
08/08/2023

Подпрограмма ExCreateCallback либо создает новый объект обратного вызова, либо открывает существующий объект обратного вызова от имени вызывающего объекта.

Синтаксис

NTSTATUS ExCreateCallback(
  [out] PCALLBACK_OBJECT   *CallbackObject,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  BOOLEAN            Create,
  [in]  BOOLEAN            AllowMultipleCallbacks
);

Параметры

[out] CallbackObject

Указатель на расположение, которое получает указатель на объект обратного вызова, который является непрозрачной системной структурой. Если вызов ExCreateCallback выполнен успешно, подпрограмма записывает в это расположение адрес только что созданного или открытого объекта обратного вызова. Указатель объекта обратного вызова, полученный из этой подпрограммы, можно предоставить в качестве параметра для подпрограммы ExRegisterCallback или ExNotifyCallback .

[in] ObjectAttributes

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

[in] Create

Указывает, следует ли создавать объект обратного вызова. Задайте значение TRUE , чтобы создать новый объект обратного вызова, если запрошенный объект не может быть открыт. В противном случае задайте значение FALSE.

[in] AllowMultipleCallbacks

Указывает, должен ли созданный объект обратного вызова разрешать несколько зарегистрированных процедур обратного вызова. Задайте значение TRUE , чтобы разрешить несколько зарегистрированных процедур обратного вызова. В противном случае задайте значение FALSE. Этот параметр игнорируется, если параметр Create имеет значение FALSE или при открытии существующего объекта.

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

ExCreateCallback возвращает STATUS_SUCCESS, если объект обратного вызова был открыт или создан. В противном случае возвращается код ошибки NTSTATUS, указывающий на характер сбоя.

Драйвер вызывает ExCreateCallback , чтобы создать новый объект обратного вызова или открыть существующий объект обратного вызова. После создания или открытия объекта другие компоненты могут вызывать подпрограмму ExRegisterCallback для регистрации процедур обратного вызова в объекте обратного вызова.

Перед вызовом ExCreateCallback драйвер должен вызвать InitializeObjectAttributes , чтобы инициализировать структуру OBJECT_ATTRIBUTES для объекта обратного вызова. Неименованные объекты обратного вызова не разрешены. Вызывающий объект должен указать имя объекта ; В противном случае вызов завершается сбоем с STATUS_UNSUCCESSFUL. Вызывающий объект должен указать атрибут OBJ_PERMANENT в объекте обратного вызова, чтобы предотвратить удаление объекта до его регистрации в диспетчере объектов. Вызывающий объект также должен указывать любые другие атрибуты, например OBJ_CASE_INSENSITIVE, которые могут потребоваться.

После завершения всех операций с объектом обратного вызова драйвер должен удалить объект, чтобы предотвратить утечку памяти. Сведения об удалении объекта, созданного с помощью атрибута объекта OBJ_PERMANENT, см. в разделе ObDereferenceObject.

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

Имя объекта обратного вызова	Использование
\Callback\SetSystemTime	Операционная система вызывает все подпрограммы обратного вызова, зарегистрированные для этого объекта при каждом изменении системного времени.
\Callback\PowerState	Операционная система вызывает все подпрограммы обратного вызова, зарегистрированные для этого объекта, всякий раз, когда изменяются определенные характеристики питания системы. Когда драйвер регистрируется для уведомления обратного вызова (путем вызова ExRegisterCallback), он может указать изменения, о которых он должен быть уведомлен.

Имя объекта обратного вызова

Использование

\Callback\SetSystemTime

Операционная система вызывает все подпрограммы обратного вызова, зарегистрированные для этого объекта при каждом изменении системного времени.

\Callback\PowerState

Операционная система вызывает все подпрограммы обратного вызова, зарегистрированные для этого объекта, всякий раз, когда изменяются определенные характеристики питания системы. Когда драйвер регистрируется для уведомления обратного вызова (путем вызова ExRegisterCallback), он может указать изменения, о которых он должен быть уведомлен.

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

Требования

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

См. также раздел

ExNotifyCallback

ExRegisterCallback

InitializeObjectAttributes

ObDereferenceObject