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 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 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 sulle API e sui thread del pool di thread, 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 ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

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, chiamare 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, 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 viene impostato sullo stato segnalato, rimane in questo stato fino a quando non viene chiamato SetWaitableTimerEx 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.

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 .

Fabbisogno

Vedere anche

REASON_CONTEXT

SetWaitableTimer