Função CreateEventExA (synchapi.h)
Cria ou abre um objeto de evento nomeado ou sem nome e retorna um identificador para o objeto .
Sintaxe
HANDLE CreateEventExA(
[in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
[in, optional] LPCSTR lpName,
[in] DWORD dwFlags,
[in] DWORD dwDesiredAccess
);
Parâmetros
[in, optional] lpEventAttributes
Um ponteiro para uma estrutura SECURITY_ATTRIBUTES . Se lpEventAttributes for NULL, o identificador de evento 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, 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 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 de 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.
[in] dwFlags
Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
O estado inicial do objeto de evento é sinalizado; caso contrário, ele não está atribuído. |
|
O evento deve ser redefinido manualmente usando a função ResetEvent . Qualquer número de threads em 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.
Se esse sinalizador não for especificado, o sistema redefinirá automaticamente o evento depois de liberar um único thread de espera. |
[in] dwDesiredAccess
A máscara de acesso para o objeto de evento. Para obter uma lista de direitos de acesso, consulte Segurança do objeto de sincronização e direitos de acesso.
Valor retornado
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
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 são sinalizados. Quando uma função de espera retorna, o thread em espera é liberado para continuar sua execução.
O estado inicial do objeto de evento é especificado pelo parâmetro dwFlags . 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 em 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.
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 da herança habilitada para CreateEvent .
- Um processo pode especificar o identificador event-object 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 .
Observação
O cabeçalho synchapi.h define CreateEventEx 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
| Cliente mínimo com suporte | Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | synchapi.h (inclua Windows.h no Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de