Função IoRegisterContainerNotification (wdm.h)

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

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 como o seguinte IO_CONTAINER_NOTIFICATION_CLASS valor de enumeração:

• 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 implementada pelo chamador (driver). O gerenciador de E/S chama essa função para notificar o chamador quando ocorre um evento da classe indicada 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 o tipo 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 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 gerenciador 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 gerenciador 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 a rotina IoUnregisterContainerNotification .

Retornar valor

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

Código de retorno	Descrição
STATUS_INVALID_PARAMETER_1	Parameter 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	Parameter NotificationInformationLength não é igual ao tamanho da estrutura de informações de notificação necessária para uso com o valor do parâmetro NotificationClass especificado.
STATUS_ALREADY_COMMITTED	O driver já está registrado para receber notificações NotificationClass 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.

Comentários

Essa rotina pode potencialmente dar suporte a notificações de eventos em uma variedade de classes de evento. No Windows 7, essa rotina dá suporte apenas a notificações IoSessionStateNotification, que notificam um driver de modo kernel de alterações no status de sessões de usuário nas quais o driver está interessado. Para aplicativos de 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
Cliente mínimo com suporte	Disponível no Windows 7 e versões posteriores do sistema operacional Windows.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL

Confira também

IO_CONTAINER_NOTIFICATION_CLASS

IO_SESSION_NOTIFICATION_FUNCTION

IO_SESSION_STATE_NOTIFICATION

IoUnregisterContainerNotification

WTSRegisterSessionNotification