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

  • Статья

Подпрограмма IoRegisterContainerNotification регистрирует драйвер в режиме ядра для получения уведомлений об указанном классе событий.

Синтаксис

NTSTATUS
IoRegisterContainerNotification(
    _In_ IO_CONTAINER_NOTIFICATION_CLASS NotificationClass,
    _In_ PIO_CONTAINER_NOTIFICATION_FUNCTION CallbackFunction,
    _In_reads_bytes_opt_(NotificationInformationLength) PVOID NotificationInformation,
    _In_ ULONG NotificationInformationLength,
    _Out_ PVOID * CallbackRegistration
    );

Параметры

[in] NotificationClass

Указывает класс событий, для которых вызывающий объект (драйвер) запрашивает уведомления. Задайте для этого параметра следующее значение перечисления IO_CONTAINER_NOTIFICATION_CLASS :

  • IoSessionStateNotification

Дополнительные сведения см. в разделе "Примечания".

[in] CallbackFunction

Указатель на функцию обратного вызова, реализованную вызывающим элементом (драйвером). Диспетчер ввода-вывода вызывает эту функцию для уведомления вызывающей стороны при возникновении события класса, указанного в NotificationClass . Для NotificationClass = IoSessionStateNotification этот параметр является указателем на предоставленную вызывающим IO_SESSION_NOTIFICATION_FUNCTION функцию. Однако вызывающий объект должен привести этот указатель функции к типу PIO_CONTAINER_NOTIFICATION_FUNCTION в соответствии с типом параметра. Дополнительные сведения см. в разделе "Примечания".

[in, optional] NotificationInformation

Указатель на буфер, выделенный вызывающим объектом, который содержит структуру сведений об уведомлениях для события класса, указанного в NotificationClass. Для NotificationClass = IoSessionStateNotificationNotificationInformation указывает на IO_SESSION_STATE_NOTIFICATION структуру. Вызывающий объект должен заполнить эту структуру перед вызовом IoRegisterContainerNotification. Во время этого вызова IoRegisterContainerNotification копирует данные из этой структуры, а диспетчер ввода-вывода не получает доступа к копии структуры драйвера после возврата вызова.

[in] NotificationInformationLength

Размер (в байтах) структуры уведомлений, содержащейся в буфере, на который указывает NotificationInformation. Для NotificationClass = IoSessionStateNotification задайте для этого параметра значение sizeof(IO_SESSION_STATE_NOTIFICATION).

[out] CallbackRegistration

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

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

IoRegisterContainerNotification возвращает STATUS_SUCCESS, если вызов выполнен успешно. Возможные возвращаемые значения ошибок:

Код возврата Описание
STATUS_INVALID_PARAMETER_1 Параметр NotificationClass не является допустимой константой перечисления IO_CONTAINER_NOTIFICATION_CLASS .
STATUS_INVALID_PARAMETER_3 Неверные сведения в структуре, на которую указывает NotificationInformation .
STATUS_INVALID_PARAMETER_4 Параметр NotificationInformationLength не равен размеру структуры сведений об уведомлениях, необходимой для использования с указанным значением параметра NotificationClass .
STATUS_ALREADY_COMMITTED Драйвер уже зарегистрирован для получения уведомлений NotificationClass о событиях, связанных с указанным объектом ввода-вывода.
STATUS_INSUFFICIENT_RESOURCES У операционной системы недостаточно ресурсов для создания запрошенной регистрации.

Комментарии

Эта подпрограмма потенциально может поддерживать уведомления о событиях в различных классах событий. В Windows 7 эта подпрограмма поддерживает только уведомления IoSessionStateNotification , которые уведомляют драйвер в режиме ядра об изменениях в состоянии пользовательских сеансов, которые интересуют драйвер. Для приложений в пользовательском режиме аналогичную роль занимает функция WTSRegisterSessionNotification .

Тип указателя функции для параметра CallbackFunction определяется следующим образом:

typedef NTSTATUS
  (*PIO_CONTAINER_NOTIFICATION_FUNCTION)(
    );

Вызывающий объект должен привести указатель функции обратного вызова к этому типу, чтобы он соответствовал типу параметра CallbackFunction . IoRegisterContainerNotification определяет фактический тип указателя функции обратного вызова из параметра NotificationClass . Для NotificationClass = IoSessionStateNotificationCallbackFunction указывает на IO_SESSION_NOTIFICATION_FUNCTION функцию.

Требования

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

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

IO_CONTAINER_NOTIFICATION_CLASS

IO_SESSION_NOTIFICATION_FUNCTION

IO_SESSION_STATE_NOTIFICATION

IoUnregisterContainerNotification

WTSRegisterSessionNotification