Funzione WdfTimerCreate (wdftimer.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfTimerCreate crea un oggetto timer del framework.

Sintassi

NTSTATUS WdfTimerCreate(
  [in]  PWDF_TIMER_CONFIG      Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFTIMER               *Timer
);

Parametri

[in] Config

Puntatore a una struttura WDF_TIMER_CONFIG .

[in] Attributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES che contiene gli attributi dell'oggetto per il nuovo oggetto timer.

[out] Timer

Puntatore a una posizione che riceve un handle per il nuovo oggetto timer del framework.

Valore restituito

WdfTimerCreate restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_WDF_PARENT_NOT_SPECIFIED	Il parametro Attributes è NULL o il membro ParentObject della struttura WDF_OBJECT_ATTRIBUTES specificata da Attributes è NULL.
STATUS_INVALID_PARAMETER	È stato specificato un parametro non valido.
STATUS_INVALID_DEVICE_REQUEST	Il membro ParentObject della struttura WDF_OBJECT_ATTRIBUTES non ha fatto riferimento a un oggetto dispositivo framework o a un oggetto la cui catena di elementi padre conduce a un oggetto dispositivo framework.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Il membro AutomaticSerialization della struttura WDF_TIMER_CONFIG è stato impostato su TRUE, ma il livello di esecuzione dell'oggetto dispositivo padre è stato impostato su WdfExecutionLevelPassive.

Per un elenco di altri valori restituiti che il metodo WdfTimerCreate potrebbe restituire, vedere Errori di creazione di oggetti framework.

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

Commenti

Quando il driver chiama WdfTimerCreate, deve fornire una struttura WDF_OBJECT_ATTRIBUTES e deve specificare un oggetto padre nel membro ParentObject della struttura. L'oggetto padre può essere un oggetto dispositivo framework o qualsiasi oggetto la cui catena di elementi padre porta a un oggetto dispositivo framework. Il framework eliminerà l'oggetto timer quando elimina l'oggetto dispositivo.

Dopo aver creato un oggetto timer, il driver deve chiamare WdfTimerStart per avviare l'orologio del timer indipendentemente dal fatto che il timer sia periodico o meno.

Se il driver fornisce funzioni di callback EvtCleanupCallback o EvtDestroyCallback per l'oggetto timer del framework, si noti che il framework chiama queste funzioni di callback in IRQL = PASSIVE_LEVEL.

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

Esempio

Nell'esempio di codice seguente viene inizializzata una struttura WDF_TIMER_CONFIG e una struttura WDF_OBJECT_ATTRIBUTES e quindi viene chiamata WdfTimerCreate.

WDF_TIMER_CONFIG  timerConfig;
WDF_OBJECT_ATTRIBUTES  timerAttributes;
WDFTIMER  timerHandle;
NTSTATUS  status;

WDF_TIMER_CONFIG_INIT(
                      &timerConfig,
                      MyEvtTimerFunc
                      );

timerConfig.AutomaticSerialization = TRUE;

WDF_OBJECT_ATTRIBUTES_INIT(&timerAttributes);
timerAttributes.ParentObject = DeviceHandle;

status = WdfTimerCreate(
                        &timerConfig,
                        &timerAttributes,
                        &timerHandle
                        );

if (!NT_SUCCESS(status)) {
    return status;
}

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)