WdfTimerCreate, fonction (wdftimer.h)

Article
02/29/2024

[S’applique à KMDF et UMDF]

La méthode WdfTimerCreate crée un objet de minuteur d’infrastructure.

Syntaxe

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

Paramètres

[in] Config

Pointeur vers une structure WDF_TIMER_CONFIG .

[in] Attributes

Pointeur vers une structure WDF_OBJECT_ATTRIBUTES qui contient des attributs d’objet pour le nouvel objet minuteur.

[out] Timer

Pointeur vers un emplacement qui reçoit un handle vers le nouvel objet de minuteur d’infrastructure.

Valeur retournée

WdfTimerCreate retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_WDF_PARENT_NOT_SPECIFIED	Le paramètre Attributes était NULL ou le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES spécifiée par Attributes était NULL.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été spécifié.
STATUS_INVALID_DEVICE_REQUEST	Le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES ne référence pas un objet d’appareil framework ou un objet dont la chaîne de parents conduit à un objet d’appareil framework.
STATUS_INSUFFICIENT_RESOURCES	La mémoire était insuffisante.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Le membre AutomaticSerialization de la structure WDF_TIMER_CONFIG a été défini sur TRUE, mais le niveau d’exécution de l’objet d’appareil parent a été défini sur WdfExecutionLevelPassive.

Pour obtenir la liste des autres valeurs de retour que la méthode WdfTimerCreate peut retourner, consultez Erreurs de création d’objet Framework.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

Remarques

Lorsque votre pilote appelle WdfTimerCreate, il doit fournir une structure WDF_OBJECT_ATTRIBUTES et spécifier un objet parent dans le membre ParentObject de la structure. L’objet parent peut être un objet d’appareil framework ou tout objet dont la chaîne de parents conduit à un objet d’appareil framework. L’infrastructure supprime l’objet minuteur lorsqu’il supprime l’objet d’appareil.

Après avoir créé un objet minuteur, le pilote doit appeler WdfTimerStart pour démarrer l’horloge du minuteur, que le minuteur soit périodique ou non.

Si votre pilote fournit des fonctions de rappel EvtCleanupCallback ou EvtDestroyCallback pour l’objet de minuteur d’infrastructure, notez que l’infrastructure appelle ces fonctions de rappel à l’adresse IRQL = PASSIVE_LEVEL.

Pour plus d’informations sur les objets du minuteur d’infrastructure, consultez Utilisation des minuteurs.

Exemples

L’exemple de code suivant initialise une structure WDF_TIMER_CONFIG et une structure WDF_OBJECT_ATTRIBUTES , puis appelle 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;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdftimer.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)