Funzione CreateTimerQueueTimer (threadpoollegacyapiset.h)

Crea un timer della coda timer. Questo timer scade alla scadenza specificata, quindi dopo ogni periodo specificato. Alla scadenza del timer, viene chiamata la funzione di callback.

Sintassi

BOOL CreateTimerQueueTimer(
  [out]          PHANDLE             phNewTimer,
  [in, optional] HANDLE              TimerQueue,
  [in]           WAITORTIMERCALLBACK Callback,
  [in, optional] PVOID               Parameter,
  [in]           DWORD               DueTime,
  [in]           DWORD               Period,
  [in]           ULONG               Flags
);

Parametri

[out] phNewTimer

Puntatore a un buffer che riceve un handle per il timer della coda timer al ritorno. Quando questo handle è scaduto e non è più necessario, rilasciarlo chiamando DeleteTimerQueueTimer.

[in, optional] TimerQueue

Handle per la coda timer. Questo handle viene restituito dalla funzione CreateTimerQueue .

Se questo parametro è NULL, il timer è associato alla coda timer predefinita.

[in] Callback

Puntatore alla funzione definita dall'applicazione di tipo WAITORTIMERCALLBACK da eseguire alla scadenza del timer. Per altre informazioni, vedere WaitOrTimerCallback.

[in, optional] Parameter

Valore di un singolo parametro che verrà passato alla funzione di callback.

[in] DueTime

Quantità di tempo in millisecondi rispetto all'ora corrente che deve trascorrere prima che il timer venga segnalato per la prima volta.

[in] Period

Periodo del timer, espresso in millisecondi. Se questo parametro è zero, il timer viene segnalato una volta. Se questo parametro è 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.

[in] Flags

Questo parametro può essere uno o più dei valori seguenti di WinNT.h.

Valore Significato
WT_EXECUTEDEFAULT
0x00000000
Per impostazione predefinita, la funzione di callback viene accodata a un thread di lavoro non I/O.
WT_EXECUTEINTIMERTHREAD
0x00000020
La funzione di callback viene richiamata dal thread timer stesso. Questo flag deve essere usato solo per attività brevi o può influire su altre operazioni timer.

La funzione di callback viene accodata come APC. Non deve eseguire operazioni di attesa di avviso.

WT_EXECUTEINIOTHREAD
0x00000001
Questo flag non viene usato.

Windows Server 2003 e Windows XP: La funzione di callback viene accodata a un thread di lavoro di I/O. Questo flag deve essere usato se la funzione deve essere eseguita in un thread che attende in uno stato di avviso.

I thread di lavoro di I/O sono stati rimossi a partire da Windows Vista e Windows Server 2008.

WT_EXECUTEINPERSISTENTTHREAD
0x00000080
La funzione di callback viene accodata a un thread che non termina mai. Non garantisce che lo stesso thread venga usato ogni volta. Questo flag deve essere usato solo per attività brevi o può influire su altre operazioni timer.

Questo flag deve essere impostato se il thread chiama le funzioni che usano LEC. Per altre informazioni, vedere Chiamate di routine asincrone.

Si noti che attualmente nessun thread di lavoro è veramente persistente, anche se nessun thread di lavoro verrà terminato se sono presenti richieste di I/O in sospeso.

WT_EXECUTELONGFUNCTION
0x00000010
La funzione di callback può eseguire un'attesa prolungata. Questo flag consente al sistema di decidere se deve creare un nuovo thread.
WT_EXECUTEONLYONCE
0x00000008
Il timer verrà impostato sullo stato segnalato una sola volta. Se questo flag è impostato, il parametro Period deve essere zero.
WT_TRANSFER_IMPERSONATION
0x00000100
Le funzioni di callback useranno il token di accesso corrente, indipendentemente dal fatto che si tratti di un processo o di un token di rappresentazione. Se questo flag non viene specificato, le funzioni di callback vengono eseguite solo con il token di processo.

Windows XP: Questo flag non è supportato fino a quando Windows XP con SP2 e Windows Server 2003.

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

Se i parametri DueTime e Period sono entrambi diversi da zero, il timer verrà segnalato per primo alla scadenza, quindi periodicamente. Il callback viene chiamato ogni volta che il periodo è trascorso, indipendentemente dal fatto che il callback precedente abbia terminato l'esecuzione. Le funzioni di callback vengono accodate al pool di thread. Questi thread sono soggetti a ritardi di pianificazione, quindi la tempistica può variare a seconda di ciò che accade nell'applicazione o nel sistema.

Il tempo trascorso dal sistema durante la sospensione o l'ibernazione non viene conteggiato alla scadenza del timer. Il timer viene segnalato quando la quantità cumulativa di tempo trascorso che il sistema impiega nello stato di riattivazione corrisponde al tempo o al periodo di scadenza del timer.

Windows Server 2003 e Windows XP: Il tempo trascorso dal sistema durante la sospensione o l'ibernazione viene conteggiato verso la scadenza del timer. Se il timer scade mentre il sistema è in sospensione, il timer viene segnalato immediatamente alla riattivazione del sistema.

Per annullare un timer, chiamare la funzione DeleteTimerQueueTimer . Per annullare tutti i timer in una coda timer, chiamare la funzione DeleteTimerQueueEx .

Per impostazione predefinita, il pool di thread ha un massimo di 500 thread. Per aumentare questo limite, usare la macro WT_SET_MAX_THREADPOOL_THREAD definita in WinNT.h.

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)<<16)

Utilizzare questa macro quando si specifica il parametro Flags . I parametri della macro sono i flag desiderati e il nuovo limite (fino a (2<<16)-1 thread. Si noti tuttavia che l'applicazione può migliorare le prestazioni mantenendo basso il numero di thread di lavoro.

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

Esempio

Per un esempio che usa CreateTimerQueueTimer, vedere Uso delle code timer.

Requisiti

Requisito Valore
Client minimo supportato Windows XP [solo app desktop]
Server minimo supportato Windows Server 2003 [solo app desktop]
Piattaforma di destinazione Windows
Intestazione threadpoollegacyapiset.h
Libreria Kernel32.lib
DLL Kernel32.dll

Vedere anche

CreateTimerQueue

DeleteTimerQueueEx

DeleteTimerQueueTimer

Funzioni di sincronizzazione

Pooling dei thread

Code timer