Função IoCreateNotificationEvent (wdm.h)

Artigo
08/08/2023

A rotina IoCreateNotificationEvent cria ou abre um evento de notificação nomeado usado para notificar um ou mais threads de execução de que um evento ocorreu.

Sintaxe

PKEVENT IoCreateNotificationEvent(
  [in]  PUNICODE_STRING EventName,
  [out] PHANDLE         EventHandle
);

Parâmetros

[in] EventName

Ponteiro para um buffer que contém uma cadeia de caracteres Unicode terminada em nulo que nomeia o evento.

[out] EventHandle

Ponteiro para um local no qual retornar um identificador de kernel para o objeto de evento.

Retornar valor

IoCreateNotificationEvent retornará um ponteiro para o objeto de evento criado ou aberto ou NULL se o objeto de evento não puder ser criado ou aberto.

Comentários

Se o objeto de evento ainda não existir, IoCreateNotificationEvent o criará e o abrirá e definirá seu estado como Signaled.

Se o objeto de evento já existir, IoCreateNotificationEvent apenas abrirá o objeto de evento.

Eventos de notificação e eventos de sincronização são usados para coordenar a execução. No entanto, enquanto um evento de sincronização é redefinido, um evento de notificação permanece no estado Sinalizado até que o driver chame KeClearEvent ou KeResetEvent.

Para sincronizar em um evento de notificação:

Abra o evento de notificação com IoCreateNotificationEvent. Identifique o evento com a cadeia de caracteres EventName .
Aguarde até que o evento seja sinalizado chamando KeWaitForSingleObject com o PKEVENT retornado por IoCreateNotificationEvent. Mais de um thread de execução pode aguardar um determinado evento de notificação. Para sondar em vez de parar, especifique um Tempo limite de zero para KeWaitForSingleObject.
Feche o identificador do evento de notificação com ZwClose quando o acesso ao evento não for mais necessário.

Há dois métodos main para compartilhar objetos de evento:

O aplicativo de modo de usuário cria o objeto de evento e passa um identificador para o objeto para o driver enviando um IOCTL para o driver. O driver deve manipular o IOCTL no contexto do processo que criou o objeto de evento e deve validar o identificador chamando ObReferenceObjectByHandle. Esse método é o método recomendado para compartilhar objetos de evento entre modos de usuário e kernel.
O driver cria um objeto de evento nomeado no diretório de objeto global \BaseNamedObjects . Para acessar um evento do modo kernel do modo de usuário, use o nome Global\\Xxx. Observe que as configurações de segurança podem impedir que um aplicativo abra o evento. O \\BaseNamedObjects diretório do objeto não é criado até que o subsistema Microsoft Win32 seja inicializado, portanto, os drivers carregados no momento da inicialização não podem criar objetos de evento no \\BaseNamedObjects diretório em suas rotinas DriverEntry .

Para obter mais informações sobre eventos, consulte Event Objects.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 2000.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	HwStorPortProhibitedDDIs(storport), IrqlIoPassive4(wdm)