Função IoCreateSynchronizationEvent (wdm.h)

  • Artigo

A rotina IoCreateSynchronizationEvent cria ou abre um evento de sincronização nomeado para uso na serialização de 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.

Retornar valor

IoCreateSynchronizationEvent 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

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 um evento de sincronização chama 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 é redefinido automaticamente para o estado Not-Signaled.

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

O compartilhamento de objetos de evento entre o modo de usuário e o modo kernel requer cuidado. 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 diretório de objeto \BaseNamedObjects 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 diretório \BaseNamedObjects 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 Ntddk.h)
Biblioteca NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
Regras de conformidade da DDI HwStorPortProhibitedDIs(storport), IrqlIoPassive4(wdm), PowerIrpDDis(wdm)

Confira também

IoCreateNotificationEvent

KeWaitForSingleObject

RtlInitUnicodeString

ZwClose