Função CreateWaitableTimerW (synchapi.h)
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 .
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 |