Macro ObReferenceObjectWithTag (wdm.h)

La routine ObReferenceObjectWithTag incrémente le nombre de références de l’objet spécifié et écrit une valeur de balise de quatre octets dans l’objet pour prendre en charge le suivi des références d’objet.

Syntaxe

void ObReferenceObjectWithTag(
  [in]  Object,
  [in]  Tag
);

Paramètres

[in] Object

Pointeur vers l’objet . L’appelant obtient ce pointeur lors de la création de l’objet, ou à partir d’un appel précédent à la routine ObReferenceObjectByHandleWithTag après l’ouverture de l’objet.

[in] Tag

Spécifie une valeur de balise personnalisée de quatre octets. Pour plus d'informations, consultez la section Notes qui suit.

Valeur de retour

None

Remarques

ObReferenceObjectWithTag retourne une valeur réservée à l’utilisation du système. Les pilotes doivent traiter cette valeur comme VOID.

ObReferenceObjectWithTag incrémente simplement le nombre de références de pointeurs pour un objet, sans effectuer de vérifications d’accès sur l’objet spécifié. En revanche, les routines ObReferenceObjectByHandleWithTag et ObReferenceObjectByPointerWithTag vérifient que l’appelant dispose des droits d’accès requis à l’objet et échouent si l’appelant ne dispose pas de ces droits.

Un appel ObReferenceObjectWithTag empêche la suppression de l’objet spécifié au moins jusqu’à ce que le pilote appelle la routine ObDereferenceObjectWithTag ou ferme l’objet. Une fois que l’objet n’est plus nécessaire, le pilote doit appeler ObDereferenceObjectWithTag pour supprimer sa référence à l’objet .

Lorsque le nombre de références pour un objet atteint zéro, un composant en mode noyau peut supprimer l’objet. Toutefois, un pilote peut supprimer uniquement les objets qu’il a créés, et un pilote ne doit jamais tenter de supprimer un objet qu’il n’a pas créé.

Pour plus d’informations sur les références d’objets, consultez Cycle de vie d’un objet.

La routine ObReferenceObject est similaire à ObReferenceObjectWithTag, sauf qu’elle ne permet pas à l’appelant d’écrire une balise personnalisée dans un objet. Dans Windows 7 et versions ultérieures de Windows, ObReferenceObject écrit toujours une valeur de balise par défaut (« tlfD ») dans l’objet . Un appel à ObReferenceObject a le même effet qu’un appel à ObReferenceObjectWithTag qui spécifie Tag = 'tlfD'.

Pour afficher une trace de référence d’objet dans les outils de débogage Windows, utilisez l’extension de débogueur en mode noyau !obtrace . Dans Windows 7, l’extension !obtrace est améliorée pour afficher les balises de référence d’objet, si le suivi des références d’objet est activé. Par défaut, le suivi des références d’objets est désactivé. Utilisez l’éditeur d’indicateurs globaux (Gflags) pour activer le suivi des références d’objets. Pour plus d’informations, consultez Suivi de référence d’objet avec des balises.

Configuration requise

Voir aussi

ObDereferenceObjectWithTag

ObReferenceObject

ObReferenceObjectByHandleWithTag

ObReferenceObjectByPointerWithTag