Funzione SetWaitableTimer (synchapi.h)

Articolo
11/18/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 CreateWaitableTimer o funzione 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.

[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 il tempo relativo. L'accuratezza del timer effettiva dipende dalla funzionalità dell'hardware. Per altre informazioni sull'ora utc, vedere ora di sistema.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 e Windows Server 2008 R2: Se viene specificato un tempo relativo, il timer include tempo trascorso in stati a basso consumo. Ad esempio, il timer continua a contare mentre il computer è in stato di sospensione.

Windows 8 e versioni successive, Windows Server 2012 e versioni successive: Se viene specificato il tempo relativo, il timer non include il tempo impiegato in stati a basso consumo. Ad esempio, il timer non continua a contare mentre il computer è in stato di sospensione.

[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 utilizzando la funzione CancelWaitableTimer o reimpostata utilizzando 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 sulle API e sui thread del pool di thread, 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 ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

I timer sono inizialmente inattivi. Per attivare un timer, chiamare 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, pertanto 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 così come 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 pfnCompletionRoutine parametro o un altro meccanismo di segnalazione basato su APC, usare un oggetto waitable, ad esempio un timer creato con CreateThreadpoolTimer. Per L'I/O, usare un oggetto di completamento I/O creato con CreateThreadpoolIo o una struttura di hEventbasata su OVERLAPPED 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, la terminazione 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 non viene chiamato SetWaitableTimer 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 eventuali 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 di timeBeginPeriod e timeEndPeriod. Il modo in cui è possibile modificare la risoluzione dipende dall'orologio hardware usato dall'API specifica. Per altre informazioni, vedere la documentazione hardware.

Esempi

Per un esempio che usa SetWaitableTimer, vedere Using Waitable Timer Objects.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [app desktop \| App UWP]
server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
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