Função IoCreateSynchronizationEvent (wdm.h)

Artigo
02/07/2025

A rotina IoCreateSynchronizationEvent cria ou abre um evento de sincronização nomeado para uso na serialização do acesso ao hardware entre dois drivers não relacionados.

Sintaxe

PKEVENT IoCreateSynchronizationEvent(
  [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 para o objeto de evento. No Windows Server 2003 e versões posteriores do Windows, o identificador retornado é um identificador de kernel .

Valor de retorno

IoCreateSynchronizationEvent retorna um ponteiro para o objeto de evento criado ou aberto ou NULL se o objeto de evento não puder ser criado ou aberto.

Observações

O objeto de evento será criado se ele ainda não existir. IoCreateSynchronizationEvent define o estado de um novo evento de sincronização como Signaled. Se o objeto de evento já existir, ele será simplesmente aberto. O par de drivers que usam uma chamada de evento de sincronização KeWaitForSingleObject com o ponteiro PKEVENT retornado por essa rotina.

Quando um evento de sincronização é definido como o estado Sinalizado, um único thread de execução que estava aguardando o evento é liberado e o evento é automaticamente redefinido para o estado Not-Signaled.

Para liberar o evento, um driver chama ZwClose com o identificador de evento.

Compartilhar objetos de evento entre o modo de usuário e o modo kernel requer cuidado. Há dois métodos principais 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 os modos de usuário e kernel.
O driver cria um objeto de evento nomeado no diretório de objeto \BaseNamedObjects global. Para acessar um evento no 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 diretório de objetos \BaseNamedObjects não é criado até que o subsistema Microsoft Win32 seja inicializado, portanto, os drivers carregados no tempo de inicialização não podem criar objetos de evento no diretório \BaseNamedObjects em suas rotinas de do DriverEntry

Para obter mais informações sobre eventos, consulte objetos de evento.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível a partir do Windows 2000.
da Plataforma de Destino	Universal
cabeçalho	wdm.h (inclua Ntddk.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), IrqlIoPassive4(wdm), PowerIrpDDis(wdm)

Consulte também

IoCreateNotificationEvent

KeWaitForSingleObject

rtlInitUnicodeString

ZwClose

Compartilhar via