Funzione SetWaitableTimer (synchapi.h)

Articolo
03/02/2024

Attiva il timer waitable specificato. 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 SetWaitableTimer(
  [in]           HANDLE              hTimer,
  [in]           const LARGE_INTEGER *lpDueTime,
  [in]           LONG                lPeriod,
  [in, optional] PTIMERAPCROUTINE    pfnCompletionRoutine,
  [in, optional] LPVOID              lpArgToCompletionRoutine,
  [in]           BOOL                fResume
);

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 SetWaitableTimer. Se lPeriod è minore di zero, la funzione ha esito negativo.

[in, optional] 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, optional] lpArgToCompletionRoutine

Puntatore a una struttura passata alla routine di completamento.

[in] fResume

Se questo parametro è TRUE, ripristina un sistema in modalità di risparmio energia sospesa quando lo stato del timer è impostato su segnalato. In caso contrario, il sistema non viene ripristinato. Se il sistema non supporta un ripristino, la chiamata ha esito positivo, ma GetLastError restituisce ERROR_NOT_SUPPORTED.

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

I timer sono inizialmente inattivi. Per attivare un timer, chiama SetWaitableTimer. Se il timer è già attivo quando si chiama SetWaitableTimer, 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 SetWaitableTimer 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.

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

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

Le API che gestiscono i timer usano diversi orologi hardware. Questi orologi possono avere risoluzioni significativamente diverse da quelle previste: alcuni possono essere misurati in millisecondi (per quelli che usano un chip timer basato su RTC), a quelli misurati in nanosecondi (per quelli che usano contatori ACPI o TSC). È possibile modificare la risoluzione dell'API con una chiamata alle funzioni timeBeginPeriod e timeEndPeriod . La precisione della modifica della risoluzione dipende dall'orologio hardware usato dall'API specifica. Per altre informazioni, vedere la documentazione relativa all'hardware.

Esempio

Per un esempio che usa SetWaitableTimer, vedere Using Waitable Timer Objects.For an example that using SetWaitableTimer, see Using Waitable Timer Objects.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	synchapi.h (include Windows.h in Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Libreria	Kernel32.lib
DLL	Kernel32.dll