Funzione SetWaitableTimerEx (synchapi.h)

Attiva il timer waitable specificato e fornisce informazioni di contesto per il timer. Quando arriva il tempo di scadenza, il timer viene segnalato e il thread che imposta il timer chiama la routine di completamento facoltativa.

Sintassi

BOOL SetWaitableTimerEx(
  [in] HANDLE              hTimer,
  [in] const LARGE_INTEGER *lpDueTime,
  [in] LONG                lPeriod,
  [in] PTIMERAPCROUTINE    pfnCompletionRoutine,
  [in] LPVOID              lpArgToCompletionRoutine,
  [in] PREASON_CONTEXT     WakeContext,
  [in] ULONG               TolerableDelay
);

Parametri

[in] hTimer

Handle per l'oggetto timer. La funzione CreateWaitableTimer o OpenWaitableTimer restituisce questo handle.

L'handle deve avere il diritto di accesso TIMER_MODIFY_STATE . Per altre informazioni, vedere Synchronization Object Security and Access Rights.For more information, see Synchronization Object Security and Access Rights.

[in] lpDueTime

Ora dopo la quale lo stato del timer deve essere impostato su segnalato, in intervalli di 100 nanosecondi. Usare il formato descritto dalla struttura FILETIME . I valori positivi indicano l'ora assoluta. Assicurarsi di usare un'ora assoluta basata su UTC, perché il sistema usa internamente l'ora utc. I valori negativi indicano l'ora relativa. L'accuratezza del timer effettiva dipende dalla funzionalità dell'hardware. Per altre informazioni sull'ora utc, vedere Ora di sistema.

[in] lPeriod

Periodo del timer, espresso in millisecondi. Se lPeriod è zero, il timer viene segnalato una volta. Se lPeriod è maggiore di zero, il timer è periodico. Un timer periodico riattiva automaticamente ogni volta che il periodo scade, fino a quando il timer non viene annullato usando la funzione CancelWaitableTimer o reimpostato usando SetWaitableTimerEx. Se lPeriod è minore di zero, la funzione ha esito negativo.

[in] pfnCompletionRoutine

Puntatore a una routine di completamento facoltativa. La routine di completamento è una funzione definita dall'applicazione di tipo PTIMERAPCROUTINE da eseguire quando viene segnalato il timer. Per altre informazioni sulla funzione di callback timer, vedere TimerAPCProc. Per altre informazioni sui thread del pool di thread e sulle schede AFC, vedere Osservazioni.

[in] lpArgToCompletionRoutine

Puntatore a una struttura passata alla routine di completamento.

[in] WakeContext

Puntatore a una struttura REASON_CONTEXT che contiene informazioni di contesto per il timer.

[in] TolerableDelay

Ritardo tollerabile per la scadenza, espresso in millisecondi.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

La funzione SetWaitableTimerEx è simile alla funzione SetWaitableTimer , ad eccezione di SetWaitableTimerEx può essere usata per specificare una stringa di contesto e un ritardo tollerabile per la scadenza del timer.

Per compilare un'applicazione che usa questa funzione, definire _WIN32_WINNT come 0x0601 o versione successiva. Per altre informazioni, vedere Uso delle intestazioni di Windows.

I timer sono inizialmente inattivi. Per attivare un timer, chiama SetWaitableTimerEx. Se il timer è già attivo quando si chiama SetWaitableTimerEx, il timer viene arrestato, viene riattivato. L'arresto del timer in questo modo non imposta lo stato del timer su segnalato, quindi i thread bloccati in un'operazione di attesa sul timer rimangono bloccati. Tuttavia, annulla tutte le routine di completamento in sospeso.

Quando arriva il tempo di scadenza specificato, il timer diventa inattivo e l'APC facoltativo viene accodato al thread che imposta il timer se non è già in coda APC in sospeso. Lo stato del timer è impostato su segnalato, il timer viene riattivato usando il periodo specificato e il thread che imposta il timer chiama la routine di completamento quando entra in uno stato di attesa avvisabile. Per altre informazioni, vedere QueueUserAPC. Si noti che le API non funzionano e altri meccanismi di segnalazione per i thread del pool di thread perché il sistema controlla la durata dei thread del pool di thread, quindi è possibile che un thread venga terminato prima che venga recapitata la notifica. Anziché usare il parametro pfnCompletionRoutine o un altro meccanismo di segnalazione basato su APC, usare un oggetto waitable, ad esempio un timer creato con CreateThreadpoolTimer. Per I/O, usare un oggetto di completamento I/O creato con CreateThreadpoolIo o una struttura OVERLAPPED basata su hEvent in cui l'evento può essere passato alla funzione SetThreadpoolWait.

Se il thread che imposta il timer termina ed è presente una routine di completamento associata, il timer viene annullato. Tuttavia, lo stato del timer rimane invariato. Se non è presente alcuna routine di completamento, l'interruzione del thread non ha alcun effetto sul timer.

Quando un timer di reimpostazione manuale è impostato sullo stato segnalato, rimane in questo stato fino a quando SetWaitableTimerEx non viene chiamato per reimpostare il timer. Di conseguenza, un timer di reimpostazione manuale periodico viene impostato sullo stato segnalato quando arriva il tempo di scadenza iniziale e rimane segnalato fino a quando non viene reimpostato. Quando un timer di sincronizzazione è impostato sullo stato segnalato, rimane in questo stato finché un thread non completa un'operazione di attesa sull'oggetto timer.

Se l'ora di sistema viene modificata, viene regolato il tempo di scadenza di tutti i timer assoluti in sospeso.

Se il thread che ha chiamato SetWaitableTimerEx viene chiuso, il timer viene annullato. Questo arresta il timer prima che possa essere impostato sullo stato segnalato e annulla le API in sospeso; non modifica lo stato segnalato del timer.

Per usare un timer per pianificare un evento per una finestra, usare la funzione SetTimer .

Requisiti

Client minimo supportato	Windows 7 [app desktop | App UWP]
Server minimo supportato	Windows Server 2008 R2 [app desktop | App UWP]
Piattaforma di destinazione	Windows
Intestazione	synchapi.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll

Vedere anche

REASON_CONTEXT

SetWaitableTimer