Função CreateWaitableTimerW (synchapi.h)

Artigo
03/02/2024

Cria ou abre um objeto de temporizador de espera.

Para especificar uma máscara de acesso para o objeto, use a função CreateWaitableTimerEx .

Sintaxe

HANDLE CreateWaitableTimerW(
  [in, optional] LPSECURITY_ATTRIBUTES lpTimerAttributes,
  [in]           BOOL                  bManualReset,
  [in, optional] LPCWSTR               lpTimerName
);

Parâmetros

[in, optional] lpTimerAttributes

Um ponteiro para uma estrutura SECURITY_ATTRIBUTES que especifica um descritor de segurança para o novo objeto de temporizador e determina se os processos filho podem herdar o identificador retornado.

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] bManualReset

Se esse parâmetro for TRUE, o temporizador será um temporizador de notificação de redefinição manual. Caso contrário, o temporizador será um temporizador de sincronização.

[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 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.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador para o objeto de temporizador. Se o objeto de temporizador 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 CreateWaitableTimer é criado com o direito de acesso TIMER_ALL_ACCESS; ele pode ser usado em qualquer função que exija um identificador para um objeto de temporizador, desde que o chamador tenha recebido acesso. Se um temporizador for criado a partir de um serviço ou thread que representa um usuário diferente, você poderá aplicar um descritor de segurança ao temporizador 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 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 de temporizador se o parâmetro lpTimerAttributes de CreateWaitableTimer 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 de temporizador em uma chamada para a função OpenWaitableTimer ou CreateWaitableTimer .

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

Para compilar um aplicativo que usa essa função, defina _WIN32_WINNT como 0x0400 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.

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

Exemplos

Para obter um exemplo que usa CreateWaitableTimer, consulte Using Waitable Timer Objects.

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