Função DeleteTimerQueueTimer (threadpoollegacyapiset.h)

Artigo
03/02/2024

Remove um temporizador da fila do temporizador e, opcionalmente, aguarda a conclusão das funções de retorno de chamada do temporizador em execução no momento antes de excluir o temporizador.

Sintaxe

BOOL DeleteTimerQueueTimer(
  [in, optional] HANDLE TimerQueue,
  [in]           HANDLE Timer,
  [in, optional] HANDLE CompletionEvent
);

Parâmetros

[in, optional] TimerQueue

Um identificador para a fila do temporizador. Esse identificador é retornado pela função CreateTimerQueue .

Se o temporizador tiver sido criado usando a fila de temporizador padrão, esse parâmetro deverá ser NULL.

[in] Timer

Um identificador para o temporizador de fila de temporizador. Esse identificador é retornado pela função CreateTimerQueueTimer .

[in, optional] CompletionEvent

Um identificador para o objeto de evento a ser sinalizado quando o sistema cancelou o temporizador e todas as funções de retorno de chamada foram concluídas. Este parâmetro pode ser NULL.

Se esse parâmetro for INVALID_HANDLE_VALUE, a função aguardará a conclusão de qualquer função de retorno de chamada do temporizador em execução antes de retornar.

Se esse parâmetro for NULL, a função marcará o temporizador para exclusão e retornará imediatamente. Se o temporizador já tiver expirado, a função de retorno de chamada do temporizador será executada até a conclusão. No entanto, não há nenhuma notificação enviada quando a função de retorno de chamada do temporizador for concluída. A maioria dos chamadores não deve usar essa opção e deve aguardar a conclusão das funções de retorno de chamada do temporizador em execução para que possam executar qualquer limpeza necessária.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError. Se o código de erro for ERROR_IO_PENDING, não será necessário chamar essa função novamente. Para qualquer outro erro, você deve repetir a chamada.

Comentários

Essa função não pode ser chamada enquanto o thread estiver usando representação. O comportamento resultante é indefinido.

Você pode definir CompletionEvent como INVALID_HANDLE_VALUE ao chamar essa função de dentro do retorno de chamada do temporizador de outro temporizador, desde que a função de retorno de chamada não seja executada no thread do temporizador. No entanto, um deadlock poderá ocorrer se duas funções de retorno de chamada tentarem bloquear uma chamada DeleteTimerQueueTimer nos temporizadores uns dos outros. Além disso, você não pode fazer uma chamada de exclusão de bloqueio em um temporizador associado ao retorno de chamada.

Tenha cuidado ao fazer uma chamada DeleteTimerQueueTimer de bloqueio em um thread persistente. Se o temporizador que está sendo excluído tiver sido criado com WT_EXECUTEINPERSISTENTTHREAD, poderá ocorrer um deadlock.

Se houver funções de retorno de chamada pendentes e CompletionEvent for NULL, a função falhará e definirá o código de erro como ERROR_IO_PENDING. Isso indica que há funções de retorno de chamada pendentes. Esses retornos de chamada serão executados ou estarão no meio da execução. O temporizador é limpo quando a função de retorno de chamada é executada.

Para cancelar todos os temporizadores em uma fila de temporizador, chame a função DeleteTimerQueueEx .

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

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	threadpoollegacyapiset.h
Biblioteca	Kernel32.lib
DLL	Kernel32.dll