Função ZwCreateEvent (ntifs.h)
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) |
Confira também
Usando versões Nt e Zw das rotinas de serviços do sistema nativo