Função IoRegisterContainerNotification (wdm.h)

Artigo
02/07/2025

A rotina IoRegisterContainerNotification registra um driver no modo kernel para receber notificações sobre uma classe especificada de eventos.

Sintaxe

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
    );

Parâmetros

[in] NotificationClass

Especifica a classe de eventos para os quais o chamador (driver) solicita notificações. Defina esse parâmetro para o seguinte valor de enumeração IO_CONTAINER_NOTIFICATION_CLASS:

IoSessionStateNotification

Para obter mais informações, consulte a seção Comentários a seguir.

[in] CallbackFunction

Um ponteiro para uma função de retorno de chamada que é implementada pelo chamador (driver). O gerente de E/S chama essa função para notificar o chamador quando ocorre um evento da classe indicado por NotificationClass. Para NotificationClass = IoSessionStateNotification, esse parâmetro é um ponteiro para uma função de IO_SESSION_NOTIFICATION_FUNCTION fornecida pelo chamador. No entanto, o chamador deve converter esse ponteiro de função para digitar PIO_CONTAINER_NOTIFICATION_FUNCTION para corresponder ao tipo de parâmetro. Para obter mais informações, consulte a seção Comentários a seguir.

[in, optional] NotificationInformation

Um ponteiro para um buffer alocado pelo chamador que contém a estrutura de informações de notificação para um evento da classe especificada por NotificationClass. Para NotificationClass = IoSessionStateNotification, NotificationInformation aponta para uma estrutura de IO_SESSION_STATE_NOTIFICATION. O chamador deve preencher essa estrutura antes de chamar IoRegisterContainerNotification. Durante essa chamada, IoRegisterContainerNotification copia os dados dessa estrutura e o gerente de E/S não acessa a cópia da estrutura do driver após o retorno da chamada.

[in] NotificationInformationLength

O tamanho, em bytes, da estrutura de informações de notificação contida no buffer apontado por NotificationInformation. Para NotificationClass = IoSessionStateNotification, defina esse parâmetro como sizeof(IO_SESSION_STATE_NOTIFICATION).

[out] CallbackRegistration

Um ponteiro para um local no qual essa rotina grava o endereço de um objeto de registro de notificação de contêiner. Esse objeto é um objeto opaco do sistema no qual o gerente de E/S armazena informações sobre o registro de notificação de contêiner do chamador. Quando as notificações não são mais necessárias, o chamador cancela o registro passando esse ponteiro de objeto para o rotina de IoUnregisterContainerNotification.

Valor de retorno

IoRegisterContainerNotification retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os valores de retorno de erro possíveis incluem o seguinte:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER_1	NotificationClass não é uma constante de enumeração IO_CONTAINER_NOTIFICATION_CLASS válida.
STATUS_INVALID_PARAMETER_3	As informações na estrutura apontadas por NotificationInformation estão incorretas.
STATUS_INVALID_PARAMETER_4	O parâmetro NotificationInformationLength não é igual ao tamanho da estrutura de informações de notificação necessária para uso com o valor de parâmetro NotificationClass especificado.
STATUS_ALREADY_COMMITTED	O driver já está registrado para receber NotificationClass notificações de eventos associados ao objeto de E/S especificado.
STATUS_INSUFFICIENT_RESOURCES	O sistema operacional não tem recursos suficientes para criar o registro solicitado.

Observações

Essa rotina pode potencialmente dar suporte a notificações de eventos em uma variedade de classes de eventos. No Windows 7, essa rotina dá suporte apenas a notificações IoSessionStateNotification, que notificam um driver no modo kernel de alterações no status das sessões de usuário nas quais o driver está interessado. Para aplicativos no modo de usuário, a função WTSRegisterSessionNotification preenche uma função semelhante.

O tipo de ponteiro de função para o parâmetro CallbackFunction é definido da seguinte maneira:

typedef NTSTATUS
  (*PIO_CONTAINER_NOTIFICATION_FUNCTION)(
    );

O chamador deve converter o ponteiro da função de retorno de chamada para esse tipo para corresponder ao tipo de parâmetro CallbackFunction. IoRegisterContainerNotification determina o tipo real do ponteiro da função de retorno de chamada do parâmetro NotificationClass. Para NotificationClass = IoSessionStateNotification, CallbackFunction aponta para uma função IO_SESSION_NOTIFICATION_FUNCTION.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível no Windows 7 e versões posteriores do sistema operacional Windows.
da Plataforma de Destino	Universal
cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL

Consulte também

IO_CONTAINER_NOTIFICATION_CLASS

IO_SESSION_NOTIFICATION_FUNCTION

IO_SESSION_STATE_NOTIFICATION

IoUnregisterContainerNotification

WTSRegisterSessionNotification

Compartilhar via