Função CreateEventA (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 CreateEventA(
[in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
[in] BOOL bManualReset,
[in] BOOL bInitialState,
[in, optional] LPCSTR 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 membro lpSecurityDescriptor da estrutura especifica um descritor de segurança para o novo evento. Se lpEventAttributes for NULL, o evento obterá um descritor de segurança padrão. As ACLs no descritor de segurança padrão para um evento vêm do token primário ou de representação do criador.
[in] bManualReset
Se esse parâmetro for TRUE, 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 o lançamento 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 está 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 e bInitialState são ignorados porque já foram definidos pelo processo de criação. Se o parâmetro lpEventAttributes não for NULL, ele determinará se o identificador pode ser herdado, mas seu membro descritor de segurança será ignorado.
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 troca rápida de usuário é implementada usando sessões dos Serviços de Terminal. Os nomes de objetos 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.
Retornar valor
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.
Comentários
O identificador retornado por CreateEvent tem o EVENT_ALL_ACCESS direito de acesso; 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 de 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 Segurança do objeto de sincronização e direitos de acesso.
Qualquer thread do processo de chamada pode especificar o identificador event-object 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 instruídas a retornar quando qualquer um ou quando todos os objetos especificados forem 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é que seja 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 poderá herdar um identificador para um objeto de evento se o parâmetro lpEventAttributes da herança habilitada para CreateEvent .
- 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, confira Usando objetos de evento.
Observação
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 de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| 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 |
| DLL | Kernel32.dll |