Função OpenEventA (synchapi.h)

Artigo
11/20/2024

Abre um objeto de evento nomeado existente.

Sintaxe

HANDLE OpenEventA(
  [in] DWORD  dwDesiredAccess,
  [in] BOOL   bInheritHandle,
  [in] LPCSTR lpName
);

Parâmetros

[in] dwDesiredAccess

O acesso ao objeto de evento. A função falhará se o descritor de segurança do objeto especificado não permitir o acesso solicitado para o processo de chamada. Para obter uma lista de direitos de acesso, consulte de Segurança do Objeto de Sincronização e Direitos de Acesso.

[in] bInheritHandle

Se esse valor for VERDADEIRO, os processos criados por esse processo herdarão o identificador. Caso contrário, os processos não herdam esse identificador.

[in] lpName

O nome do evento a ser aberto. As comparações de nomes diferenciam maiúsculas de minúsculas.

Essa função pode abrir objetos em um namespace privado. Para obter mais informações, consulte namespaces de objeto.

Serviços de Terminal: O nome pode ter um prefixo "Global" ou "Local" para abrir explicitamente um 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.

Observação a alternância rápida de usuário é implementada usando sessões dos Serviços de Terminal. O primeiro usuário a fazer logon usa a sessão 0, o próximo usuário a fazer logon usa a sessão 1 e assim por diante. 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.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será um identificador para o objeto de evento.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Observações

A função OpenEvent permite que vários processos abram identificadores do mesmo objeto de evento. A função só terá êxito se algum processo já tiver criado o evento usando a função CreateEvent . O processo de chamada pode usar o identificador retornado em qualquer função que exija um identificador para um objeto de evento, sujeito às limitações do acesso especificado no parâmetro dwDesiredAccess.

O identificador pode ser duplicado usando a função DuplicateHandle. Use a função CloseHandle para fechar o identificador. O sistema fecha o identificador automaticamente quando o processo é encerrado. O objeto de evento é destruído quando seu último identificador foi fechado.

Nota

O cabeçalho synchapi.h define OpenEvent 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