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
[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 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.
[in] dwFlags
Esse parâmetro pode ser um ou mais dos valores a seguir.
| Valor | Significado |
|---|---|
|
O estado inicial do objeto de evento é sinalizado; caso contrário, ele não será atribuído. |
|
O evento deve ser redefinido manualmente usando a 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.
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 de Segurança do Objeto de Sincronização e Direitos de Acesso.
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
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 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é 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.
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.
Nota
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 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 Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | synchapi.h (inclua Windows.h no Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |