Função ZwOpenEvent (wdm.h)

Artigo
03/08/2023

A rotina ZwOpenEvent abre um identificador para um objeto de evento nomeado existente com o acesso desejado especificado.

Sintaxe

NTSYSCALLAPI NTSTATUS ZwOpenEvent(
  [out] PHANDLE            EventHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes
);

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] ObjectAttributes

Um ponteiro para a estrutura de atributos de objeto que o chamador forneceu para ser usado para o objeto especificado. Esses atributos incluiriam o ObjectName e os atributos de identificador, por exemplo. Esse parâmetro é inicializado chamando a macro InitializeObjectAttributes .

Retornar valor

ZwOpenEvent retorna STATUS_SUCCESS ou um status de erro apropriado. Essa rotina pode retornar um dos seguintes códigos de status de erro:

Código de retorno	Descrição
STATUS_INSUFFICIENT_RESOURCES	Recursos que essa função requer não puderam ser alocados.
STATUS_INVALID_PARAMETER	A estrutura ObjectAttributes não foi fornecida ou continha um valor de parâmetro 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 caminho do objeto continha sintaxe incorreta. Por exemplo, o parâmetro ObjectAttributes não contém um membro RootDirectory , mas o membro ObjectName na estrutura OBJECT_ATTRIBUTES é uma cadeia de caracteres vazia ou não começa com um caractere OBJECT_NAME_PATH_SEPARATOR.
STATUS_OBJECT_PATH_NOT_FOUND	O caminho para o objeto não foi encontrado, indicando que ele não existe.
STATUS_OBJECT_NAME_NOT_FOUND	O nome do objeto não foi encontrado, indicando que o objeto não existe.
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

ZwOpenEvent abre um objeto de evento nomeado existente e cria um identificador para o objeto com o acesso desejado especificado.

O ZwOpenEvent pode abrir eventos de notificação ou de sincronização.

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

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.

Se a chamada para a função ZwOpenEvent ocorrer no modo de usuário, você deverá usar o nome "NtOpenEvent" em vez de "ZwOpenEvent".

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
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)