функция обратного вызова IO_SESSION_NOTIFICATION_FUNCTION (wdm.h)

Статья
03/08/2023

Тип функции IO_SESSION_NOTIFICATION_FUNCTION определяет подпрограмму обратного вызова, с помощью которой драйвер получает уведомления об изменениях в состоянии пользовательских сеансов, в которых заинтересован драйвер.

Синтаксис

IO_SESSION_NOTIFICATION_FUNCTION IoSessionNotificationFunction;

NTSTATUS IoSessionNotificationFunction(
  [in] PVOID SessionObject,
  [in] PVOID IoObject,
  [in] ULONG Event,
  [in] PVOID Context,
  [in] PVOID NotificationPayload,
  [in] ULONG PayloadLength
)
{...}

Параметры

[in] SessionObject

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

[in] IoObject

Указатель на объект ввода-вывода, принадлежащий драйверу. Этот параметр является указателем объекта ввода-вывода, который драйвер предоставил подпрограмме IoRegisterContainerNotification , когда драйвер ранее зарегистрировал для получения уведомлений о событиях сеанса. Параметр NotificationInformation подпрограммы IoRegisterContainerNotification указывает на IO_SESSION_STATE_NOTIFICATION структуру, член которой IoObject указывает на объект ввода-вывода.

[in] Event

Константу перечисления IO_SESSION_EVENT , указывающую, какое событие сеанса вызвало обратный вызов уведомления.

[in] Context

Значение контекста, которое драйвер ранее предоставлял подпрограмме IoRegisterContainerNotification при регистрации драйвера для получения уведомлений о событиях сеанса. В вызове IoRegisterContainerNotification драйвер предоставил указатель на IO_SESSION_STATE_NOTIFICATION структуру, член которой Context содержит значение контекста.

[in] NotificationPayload

Указатель на буфер полезных данных, содержащий структуру IO_SESSION_CONNECT_INFO .

[in] PayloadLength

Размер (в байтах) буфера, на который указывает NotificationPayload. Размер буфера никогда не должен превышать значение константы IO_SESSION_MAX_PAYLOAD_SIZE, определенное в файле заголовка Wdm.h.

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

Если подпрограмма завершается успешно, она должна вернуть STATUS_SUCCESS. В противном случае он должен вернуть одно из значений состояния ошибки, определенных в файле заголовка Ntstatus.h.

Для получения уведомлений о событиях сеанса драйвер вызывает подпрограмму IoRegisterContainerNotification и задает параметр CallbackFunction этой подпрограммы, указывающий на IO_SESSION_NOTIFICATION_FUNCTION подпрограмму драйвера. Объект ввода-вывода, который драйвер передает в IoRegisterContainerNotification , определяет, будет ли драйвер получать уведомления о событиях в определенном сеансе пользователя или о событиях во всех сеансах. Дополнительные сведения см. в разделе IO_SESSION_STATE_NOTIFICATION.

Примеры

Чтобы определить подпрограмму уведомлений сеанса ввода-вывода, необходимо сначала предоставить объявление функции, определяющее тип определяемой процедуры обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить подпрограмму уведомления сеанса ввода-вывода с именем MyIoSessionNotification, используйте тип IO_SESSION_NOTIFICATION_FUNCTION, как показано в следующем примере кода:

IO_SESSION_NOTIFICATION_FUNCTION MyIoSessionNotification;

Затем реализуйте процедуру обратного вызова следующим образом:

_Use_decl_annotations_
NTSTATUS
  MyIoSessionNotification(
    PVOID  SessionObject,
    PVOID  IoObject,
    ULONG  Event,
    PVOID  Context,
    PVOID  NotificationPayload,
    ULONG  PayloadLength
    )
  {
      // Function body
  }

Тип функции IO_SESSION_NOTIFICATION_FUNCTION определяется в файле заголовка Wdm.h. Чтобы более точно определить ошибки при запуске средств анализа кода, обязательно добавьте заметку в _Use_decl_annotations_ определение функции. Заметка _Use_decl_annotations_ гарантирует использование заметок, которые применяются к типу функции IO_SESSION_NOTIFICATION_FUNCTION в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в разделе Объявление функций с помощью типов ролей функций для драйверов WDM. Дополнительные сведения о _Use_decl_annotations_см. в статье Поведение функции с заметками.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается в Windows 7 и более поздних версиях операционной системы Windows.
Целевая платформа	Персональный компьютер
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
IRQL	Вызывается в IRQL <= APC_LEVEL.