Função ZwCreateEvent (ntifs.h)

Artigo
07/11/2023

A rotina ZwCreateEvent cria um objeto de evento, define o estado inicial do evento como o valor especificado e abre um identificador para o objeto com o acesso desejado especificado.

Sintaxe

NTSYSAPI NTSTATUS ZwCreateEvent(
  [out]          PHANDLE            EventHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in]           EVENT_TYPE         EventType,
  [in]           BOOLEAN            InitialState
);

Parâmetros

[out] EventHandle

Um ponteiro para uma variável que receberá o identificador do objeto de evento. O identificador inclui informações de contabilidade, como contagem de referências e contexto de segurança.

[in] DesiredAccess

O valor ACCESS_MASK que representa os tipos de acesso desejados para o objeto de evento. A tabela a seguir contém os valores de ACCESS_MASK específicos do evento.

Valor	Acesso desejado
EVENT_QUERY_STATE	Consulte o estado do objeto de evento.
EVENT_MODIFY_STATE	Modifique o estado do objeto de evento.
EVENT_ALL_ACCESS	Todos os direitos de acesso possíveis ao objeto de evento.

[in, optional] ObjectAttributes

Um ponteiro para a estrutura de atributos de objeto fornecida pelo chamador a ser usado para o objeto especificado. Esses atributos incluem o ObjectName e o SECURITY_DESCRIPTOR, por exemplo. Esse parâmetro é inicializado chamando a macro InitializeObjectAttributes .

[in] EventType

O tipo do evento, que pode ser SynchronizationEvent ou notificationEvent. Esses valores pertencem à enumeração EVENT_TYPE , que é definida no arquivo de cabeçalho ntdef.h .

[in] InitialState

O estado inicial do objeto de evento. Defina como TRUE para inicializar o objeto de evento para o estado Sinalizado. Defina como FALSE para inicializar o objeto de evento para o estado não Sinalizado.

Retornar valor

ZwCreateEvent retorna STATUS_SUCCESS ou um erro apropriado status. Possíveis códigos de status de erro incluem o seguinte:

Código de retorno	Descrição
STATUS_INSUFFICIENT_RESOURCES	Não foi possível alocar recursos exigidos por essa função.
STATUS_INVALID_PARAMETER	A estrutura ObjectAttributes fornecida continha um valor de parâmetro inválido.
STATUS_INVALID_PARAMETER_4	O parâmetro EventType especificado era inválido.
STATUS_OBJECT_NAME_INVALID	O parâmetro ObjectAttributes continha um ObjectName na estrutura OBJECT_ATTRIBUTES inválida.
STATUS_OBJECT_PATH_SYNTAX_BAD	O parâmetro ObjectAttributes não continha um membro RootDirectory , mas o membro ObjectName na estrutura OBJECT_ATTRIBUTES era uma cadeia de caracteres vazia ou não continha um caractere OBJECT_NAME_PATH_SEPARATOR. Isso indica uma sintaxe incorreta para o caminho do objeto.
STATUS_PRIVILEGE_NOT_HELD	O chamador não tinha o privilégio necessário para criar um identificador com o acesso especificado no parâmetro DesiredAccess .

Comentários

ZwCreateEvent cria um objeto de evento, define seu estado inicial como o valor especificado e abre um identificador para o objeto com o acesso desejado especificado.

Os eventos são usados para coordenar a execução. Os eventos podem ser usados por drivers do sistema de arquivos para permitir que um chamador aguarde a conclusão da operação solicitada até que o evento especificado seja definido como o estado Sinalizado.

ZwCreateEvent pode criar eventos de notificação ou sincronização:

Eventos de notificação podem ser usados para notificar um ou mais threads de execução de que um evento ocorreu.
Os eventos de sincronização podem ser usados na serialização do acesso ao hardware entre dois drivers não relacionados.

Um evento de sincronização é a redefinição automática. Quando um evento de sincronização é definido como o estado Sinalizado, um único thread de execução que estava aguardando o evento ser sinalizado é liberado e o evento é redefinido automaticamente para o estado Not-Signaled.

Ao contrário de um evento de sincronização, um evento de notificação não é redefinido automaticamente. Depois que um evento de notificação estiver no estado Sinalizado, ele permanecerá nesse estado até que seja redefinido explicitamente.

Para sincronizar em um evento de notificação:

Crie o evento de notificação com ZwCreateEvent com o parâmetro EventType definido como NotificationEvent.
Aguarde até que o evento seja sinalizado chamando ZwWaitForSingleObject com o EventHandle retornado por ZwCreateEvent. Mais de um thread de execução pode aguardar a sinalização de um determinado evento de notificação. Para sondar em vez de parar, especifique um Tempo limite de zero para ZwWaitForSingleObject.
Feche o identificador do evento de notificação com ZwClose quando o acesso ao evento não for mais necessário.

A função ZwCreateEvent é chamada depois que a macro InitializeObjectAttributes é usada para definir atributos na estrutura OBJECT_ATTRIBUTES para o objeto.

Há duas maneiras alternativas de especificar o nome do objeto passado para ZwCreateEvent:

Como um nome de caminho totalmente qualificado, fornecido no membro ObjectName do ObjectAttributes de entrada.
Como pathname relativo ao diretório representado pelo identificador no membro RootDirectory do ObjectAttributes de entrada.

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

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

Observação

Se a chamada para a rotina ZwCreateEvent ocorrer no modo de usuário, você deverá usar o nome "NtCreateEvent" em vez de "ZwCreateEvent".

Para chamadas de drivers de modo kernel, as versões NtXxx e ZwXxx de uma rotina do Windows Native System Services podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP.
Plataforma de Destino	Universal
Cabeçalho	ntifs.h (inclua Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)