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 uma contagem de referência e um 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 incluiriam o ObjectName
[in] EventType
O tipo do evento, que pode ser
[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.
Valor de retorno
ZwCreateEvent retorna STATUS_SUCCESS ou um status de erro apropriado. Os códigos de status de erro possíveis incluem o seguinte:
| Código de retorno | Descrição |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | Não foi possível alocar recursos necessários para 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 |
| STATUS_OBJECT_NAME_INVALID | O parâmetro |
| 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 a sintaxe incorreta para o caminho do objeto. |
| STATUS_PRIVILEGE_NOT_HELD | O chamador não teve o privilégio necessário para criar um identificador com o acesso especificado no parâmetro DesiredAccess. |
Observações
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 determinado 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 ocorreu um evento.
- 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 é automaticamente redefinido 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é ser 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 pelo ZwCreateEvent. Mais de um thread de execução pode aguardar que um determinado evento de notificação seja sinalizado. Para sondar em vez de parar, especifique um de tempo limite
de zero a 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
Há duas maneiras alternativas de especificar o nome do objeto passado para ZwCreateEvent:
Como um nome de caminho totalmente qualificado, fornecido no ObjectName membro do objectAttributes de entrada.
Como nome de caminho relativo ao diretório representado pelo identificador no membro RootDirectory do de entrada ObjectAttributes.
Para liberar o evento, um driver chama ZwClose com o identificador de evento.
Para obter mais informações sobre eventos, consulte Event Objects.
Nota
Se a chamada para a rotina
Para chamadas de drivers no modo kernel, as versões NtXxx e Zwxxx versões de uma rotina dos Serviços de Sistema Nativo do Windows 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 Usando versões Nt e Zw das rotinas de serviços do sistema nativo.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP. |
| da Plataforma de Destino |
Universal |
| cabeçalho | ntifs.h (inclua Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL |
NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| regras de conformidade de DDI | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |
Consulte também
usando versões Nt e Zw das rotinas de serviços do sistema nativo