Funzione WdfTimerStart (wdftimer.h)

Articolo
03/05/2024

[Si applica a KMDF e UMDF]

Il metodo WdfTimerStart avvia l'orologio di un timer.

Sintassi

BOOLEAN WdfTimerStart(
  [in] WDFTIMER Timer,
  [in] LONGLONG DueTime
);

Parametri

[in] Timer

Handle per un oggetto timer del framework ottenuto chiamando WdfTimerCreate.

[in] DueTime

Periodo di tempo, in unità di tempo di sistema (intervalli di 100 nanosecondi). Il framework chiama la funzione di callback EvtTimerFunc del driver al termine del periodo di tempo specificato. Il valore del periodo di tempo può essere negativo o positivo come indicato di seguito:

Se il valore è negativo, il periodo di tempo è relativo all'ora di sistema corrente.
Se il valore è positivo, il periodo di tempo specifica un'ora assoluta (che è effettivamente relativa al 1° gennaio 1601).

Avviso

Se si imposta il membro UseHighResolutionTimer di WDF_TIMER_CONFIG su WdfTrue, è necessario chiamare WdfTimerStart con il parametro DueTime impostato su un valore negativo. In caso contrario, la chiamata causa l'arresto anomalo del sistema.

I tempi relativi non sono interessati da modifiche apportate all'ora di sistema che potrebbero verificarsi entro il periodo di tempo specificato. I tempi assoluti riflettono le modifiche all'ora di sistema.

Il framework fornisce funzioni di conversione dell'ora che converte i valori temporali in unità di tempo di sistema.

Valore restituito

WdfTimerStart restituisce TRUE se l'oggetto timer si trovava nella coda timer del sistema. In caso contrario, questo metodo restituisce FALSE. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Commenti

I driver devono sempre chiamare WdfTimerStart per avviare un timer dopo averlo creato, indipendentemente dal fatto che il timer sia un timer periodico o meno.

Dopo che un driver chiama WdfTimerStart, il framework chiama la funzione di callback EvtTimerFunc del driver quando scade il tempo specificato per il parametro DueTime . Dopo questa prima chiamata, il framework chiama la funzione di callback ogni volta che il periodo di tempo specificato dal membro Period della struttura WDF_TIMER_CONFIG del driver scade.

La scadenza del timer dipende in definitiva dalla granularità dell'orologio di sistema. Il valore specificato per DueTime garantisce che il framework chiami la funzione di callback EvtTimerFunc del driver in o dopo il valore DueTime specificato. Tuttavia, WdfTimerStart non può eseguire l'override della granularità dell'orologio di sistema, indipendentemente dal valore specificato per DueTime.

Quando un driver chiama WdfTimerStart, il relativo oggetto timer viene aggiunto alla coda di oggetti timer del sistema. Se il timer non è un timer periodico, il sistema rimuove l'oggetto timer dalla coda dopo che è trascorso il "tempo di scadenza" del timer. Se il timer è un timer periodico, l'oggetto timer rimane nella coda finché il driver non chiama WdfTimerStop.

Un driver potrebbe chiamare WdfTimerStart dalla funzione di callback EvtTimerFunc per riavviare un timer non periodico dopo la scadenza.

WdfTimerStart restituisce TRUE se il driver ha precedentemente chiamato WdfTimerStart e l'oggetto timer si trova ancora nella coda del sistema perché il periodo di tempo non è trascorso (o perché è un timer periodico). Prima che WdfTimerStart restituisca TRUE, il sistema operativo reimposta il periodo di tempo sul valore specificato dal driver nella nuova chiamata a WdfTimerStart. Il framework chiama la funzione di callback EvtTimerFunc solo dopo la scadenza del nuovo periodo di tempo.

Per arrestare l'orologio del timer, il driver può chiamare WdfTimerStop.

Per altre informazioni sugli oggetti timer del framework, vedere Uso di timer.

Esempio

Nell'esempio di codice seguente viene avviato un timer. Il framework chiamerà la funzione di callback EvtTimerFunc del timer dopo 10 millisecondi.

BOOLEAN inTimerQueue;

inTimerQueue = WdfTimerStart(
                             timerHandle,
                             WDF_REL_TIMEOUT_IN_MS(10)
                             );

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdftimer.h (include Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Vedi anche