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
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 de 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 VERDADEIRO, 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 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.
Valor de retorno
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.
Observações
O identificador retornado por CreateWaitableTimer é criado com o TIMER_ALL_ACCESS direito de acesso; 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 esteja representando 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 de Segurança do Objeto de Sincronização e Direitos de Acesso.
Qualquer thread do processo de chamada pode especificar o identificador de objeto do 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 do 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 Usando objetos timer de espera.
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) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |
Consulte também