Função CreateEventW (synchapi.h)
Cria ou abre um objeto de evento nomeado ou sem nome.
Para especificar uma máscara de acesso para o objeto, use a função CreateEventEx.
Sintaxe
HANDLE CreateEventW(
[in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
[in] BOOL bManualReset,
[in] BOOL bInitialState,
[in, optional] LPCWSTR lpName
);
Parâmetros
[in, optional] lpEventAttributes
Um ponteiro para uma estrutura SECURITY_ATTRIBUTES. Se esse parâmetro for NULL, o identificador não poderá ser herdado por processos filho.
O
[in] bManualReset
Se esse parâmetro for VERDADEIRO, a função criará um objeto de evento de redefinição manual, que requer o uso da função ResetEvent para definir o estado do evento como não atribuído. Se esse parâmetro for FALSE, a função criará um objeto de evento de redefinição automática e o sistema redefinirá automaticamente o estado do evento para não atribuído após a liberação de um único thread de espera.
[in] bInitialState
Se esse parâmetro for TRUE, o estado inicial do objeto de evento será sinalizado; caso contrário, ele não será atribuído.
[in, optional] lpName
O nome do objeto de evento. O nome é limitado a MAX_PATH caracteres. A comparação de nomes diferencia maiúsculas de minúsculas.
Se lpName corresponder ao nome de um objeto de evento nomeado existente, essa função solicitará o acesso EVENT_ALL_ACCESS direito. Nesse caso, os parâmetros bManualReset
Se lpName for NULL, o objeto de evento será criado sem um nome.
Se lpName corresponder ao nome de outro tipo de objeto no mesmo namespace (como um semáforo existente, mutex, temporizador de espera, trabalho ou objeto de mapeamento de arquivo), a função falhará e a função GetLastError retornará ERROR_INVALID_HANDLE. Isso ocorre porque esses objetos compartilham o mesmo namespace.
O nome pode ter um prefixo "Global" ou "Local" para criar explicitamente o objeto no namespace global ou de sessão. O restante do nome pode conter qualquer caractere, exceto o caractere de barra invertida (\). Para obter mais informações, consulte namespaces de objeto kernel. A alternância rápida de usuário é implementada usando sessões dos Serviços de Terminal. Os nomes de objeto kernel devem seguir as diretrizes descritas para os Serviços de Terminal para que os aplicativos possam dar suporte a vários usuários.
O objeto pode ser criado em um namespace privado. Para obter mais informações, consulte namespaces de objeto.
Valor de retorno
Se a função for bem-sucedida, o valor retornado será um identificador para o objeto de evento. Se o objeto de evento nomeado existir antes da chamada de função, a função retornará um identificador para o objeto existente e GetLastError retornará ERROR_ALREADY_EXISTS.
Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.
Observações
O identificador retornado por CreateEvent tem o acesso EVENT_ALL_ACCESS correto; ele pode ser usado em qualquer função que exija um identificador para um objeto de evento, desde que o chamador tenha recebido acesso. Se um evento for criado a partir de um serviço ou um thread que representa um usuário diferente, você poderá aplicar um descritor de segurança ao evento ao criá-lo ou alterar o descritor de segurança padrão para o processo de criação alterando sua DACL padrão. Para obter mais informações, consulte de Segurança do Objeto de Sincronização e Direitos de Acesso.
Qualquer thread do processo de chamada pode especificar o identificador de objeto de evento em uma chamada para uma das funções de espera . As funções de espera de objeto único retornam quando o estado do objeto especificado é sinalizado. As funções de espera de vários objetos podem ser instruidas a retornar quando qualquer um ou quando todos os objetos especificados são sinalizados. Quando uma função de espera retorna, o thread de espera é liberado para continuar sua execução.
O estado inicial do objeto de evento é especificado pelo parâmetro bInitialState. Use a função SetEvent para definir o estado de um objeto de evento como sinalizado. Use a função ResetEvent para redefinir o estado de um objeto de evento para não atribuído.
Quando o estado de um objeto de evento de redefinição manual é sinalizado, ele permanece sinalizado até ser redefinido explicitamente para não atribuído pela função ResetEvent. Qualquer número de threads de espera ou threads que, posteriormente, iniciam operações de espera para o objeto de evento especificado, pode ser liberado enquanto o estado do objeto é sinalizado.
Quando o estado de um objeto de evento de redefinição automática é sinalizado, ele permanece sinalizado até que um único thread de espera seja liberado; em seguida, o sistema redefine automaticamente o estado para não atribuído. Se nenhum thread estiver aguardando, o estado do objeto de evento permanecerá sinalizado.
Vários processos podem ter identificadores do mesmo objeto de evento, permitindo o uso do objeto para sincronização entre processos. Os seguintes mecanismos de compartilhamento de objetos estão disponíveis:
- Um processo filho criado pela função CreateProcess pode herdar um identificador para um objeto de evento se o parâmetro lpEventAttributes de CreateEvent herança habilitada.
- Um processo pode especificar o identificador de objeto de evento em uma chamada para a função
DuplicateHandle para criar um identificador duplicado que pode ser usado por outro processo. - Um processo pode especificar o nome de um objeto de evento em uma chamada para a função OpenEvent ou CreateEvent.
Exemplos
Para obter um exemplo que usa CreateEvent, consulte Usando objetos de evento.
Nota
O cabeçalho synchapi.h define CreateEvent como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | synchapi.h (inclua Windows.h no Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |
Consulte também
resetEvent