Função CreateWaitableTimerExW (synchapi.h)

Cria ou abre um objeto de temporizador de espera e retorna um identificador para o objeto .

Sintaxe

HANDLE CreateWaitableTimerExW(
  [in, optional] LPSECURITY_ATTRIBUTES lpTimerAttributes,
  [in, optional] LPCWSTR               lpTimerName,
  [in]           DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

Parâmetros

[in, optional] lpTimerAttributes

Um ponteiro para uma estrutura SECURITY_ATTRIBUTES . Se esse parâmetro for NULL, o identificador de temporizador não poderá ser herdado por processos filho.

Se lpTimerAttributes for NULL, o objeto timer obterá um descritor de segurança padrão e o identificador não poderá ser herdado. As ACLs no descritor de segurança padrão para um temporizador vêm do token primário ou de representação do criador.

[in, optional] lpTimerName

O nome do objeto de temporizador. O nome é limitado a MAX_PATH caracteres. A comparação de nomes diferencia maiúsculas de minúsculas.

Se lpTimerName for NULL, o objeto timer será criado sem um nome.

Se lpTimerName corresponder ao nome de um evento existente, semáforo, mutex, trabalho ou objeto de mapeamento de arquivo, a função falhará e 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.

[in] dwFlags

Esse parâmetro pode ser 0 ou os valores a seguir.

Valor	Significado
CREATE_WAITABLE_TIMER_MANUAL_RESET 0x00000001	O temporizador deve ser redefinido manualmente. Caso contrário, o sistema redefine automaticamente o temporizador depois de liberar um único thread de espera.
CREATE_WAITABLE_TIMER_HIGH_RESOLUTION 0x00000002	Cria um temporizador de alta resolução. Use esse valor para situações críticas de tempo quando atrasos curtos de expiração na ordem de alguns milissegundos forem inaceitáveis. Esse valor tem suporte no Windows 10, versão 1803 e posterior.

[in] dwDesiredAccess

A máscara de acesso para o objeto de temporizador. Para obter uma lista de direitos de acesso, confira Direitos de Acesso e Segurança do Objeto de Sincronização.

Valor retornado

Se a função for bem-sucedida, o valor retornado será um identificador para o objeto de temporizador. Se o objeto timer 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 de objeto de temporizador em uma chamada para uma das funções de espera.

Vários processos podem ter identificadores para o mesmo objeto de temporizador, permitindo o uso do objeto para sincronização entre processos.

• Um processo criado pela função CreateProcess pode herdar um identificador para um objeto timer se o parâmetro lpTimerAttributes de CreateWaitableTimerEx habilitar a herança.
• Um processo pode especificar o identificador de objeto de temporizador em uma chamada para a função DuplicateHandle . O identificador resultante pode ser usado por outro processo.
• Um processo pode especificar o nome de um objeto timer em uma chamada para a função OpenWaitableTimer ou CreateWaitableTimerEx .

Use a função CloseHandle para fechar o identificador. O sistema fecha o identificador automaticamente quando o processo é encerrado. O objeto timer é destruído quando seu último identificador foi fechado.

Para associar um temporizador a uma janela, use a função SetTimer .

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)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll

Confira também

CloseHandle

Funções de sincronização

Objetos de temporizador de espera