WdfObjectReferenceActual, fonction (wdfobject.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfObjectReferenceActual incrémente le nombre de références pour un objet d’infrastructure spécifié et affecte une valeur de balise, un numéro de ligne et un nom de fichier à la référence.

Syntaxe

void WdfObjectReferenceActual(
  [in]           WDFOBJECT Handle,
  [in, optional] PVOID     Tag,
  [in]           LONG      Line,
  [in]           PCCH      File
);

Paramètres

[in] Handle

Handle pour un objet framework.

[in, optional] Tag

Valeur définie par le pilote que l’infrastructure stocke en tant que balise d’identification pour la référence d’objet.

[in] Line

Valeur numérique qui représente un numéro de ligne dans un fichier source de pilote.

[in] File

Pointeur vers une chaîne de caractères constants terminée par null qui représente le nom d’un fichier source de pilote. Ce paramètre est facultatif et peut être NULL.

Valeur de retour

None

Remarques

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Si votre pilote appelle WdfObjectReferenceActual pour incrémenter un nombre de références, le pilote doit appeler WdfObjectDereferenceActual pour décrémenter le nombre.

L’appel de WdfObjectReferenceActual ou WdfObjectReferenceWithTag au lieu de WdfObjectReference fournit des informations supplémentaires (valeur de balise, numéro de ligne et nom de fichier) aux débogueurs Microsoft. WdfObjectReferenceActual permet à votre pilote de spécifier le numéro de ligne et le nom de fichier, tandis que WdfObjectReferenceWithTag utilise le numéro de ligne et le nom de fichier actuels du pilote.

Vous pouvez afficher les valeurs de balise, de numéro de ligne et de nom de fichier à l’aide de l’extension de débogueur !wdftagtracker . L’extension de débogueur affiche la valeur de balise sous la forme d’un pointeur et d’une série de caractères. Pour plus d’informations sur les extensions de débogueur, consultez Débogage d’un pilote KMDF.

Pour plus d’informations sur le nombre de références d’objets, consultez Framework Object Life Cycle.

Pour plus d’informations sur les règles de nettoyage d’une hiérarchie d’objets d’infrastructure, consultez Framework Object Life Cycle.

Exemples

L’exemple de code suivant incrémente le nombre de références d’un objet et affecte une valeur de balise, un numéro de ligne et un nom de fichier à la référence.

WdfObjectReferenceActual(
                         object,
                         pTag,
                         line,
                         FILE_NAME
                         );

Configuration requise

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

Voir aussi

WdfObjectReference

Partager via