Macro ObDereferenceObjectWithTag (wdm.h)

Article
02/27/2024

La routine ObDereferenceObjectWithTag décré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 ObDereferenceObjectWithTag(
  [in]  a,
  [in]  t
);

Paramètres

[in] a

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] t

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

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

Un pilote en mode noyau appelle cette routine pour décrémenter le nombre de références d’un objet par un. Si l’objet a été créé en tant que temporaire (autrement dit, l’indicateur OBJ_PERMANENT n’a pas été spécifié lors de la création de l’objet) et que le nombre de références atteint zéro, le gestionnaire d’objets supprime 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éé.

Un objet est permanent s’il a été créé avec l’indicateur d’attribut d’objet OBJ_PERMANENT spécifié. (Pour plus d’informations sur les attributs d’objet, consultez InitializeObjectAttributes.) Un objet permanent est créé avec un nombre de références initial d’un, de sorte que l’objet n’est pas supprimé lorsque le pilote supprime sa dernière référence à l’objet.

Pour préparer un objet permanent à supprimer, un pilote peut appeler la routine ZwMakeTemporaryObject pour rendre l’objet temporaire. Un pilote doit uniquement supprimer un objet permanent qu’il a créé. Procédez comme suit pour supprimer un objet permanent :

Appelez ObDereferenceObjectWithTag.
Obtenez le handle de l’objet. Si nécessaire, appelez la routine ZwOpenXxx ou ZwCreateXxx appropriée pour obtenir le handle de l’objet.
Appelez ZwMakeTemporaryObject avec le handle obtenu à l’étape 2.
Appelez ZwClose avec le handle obtenu à l’étape 2.

Si la suppression immédiate d’un objet par le thread actuel peut provoquer un blocage, n’appelez pas ObDereferenceObjectWithTag pour déréférencer l’objet. Au lieu de cela, appelez la routine ObDereferenceObjectDeferDeleteWithTag pour déréférencer l’objet.

Par exemple, un tel blocage peut se produire si ObDereferenceObjectWithTag est utilisé pour déréférencer un objet KTM ( Kernel Transaction Manager ) lorsqu’un pilote de niveau supérieur sur la pile de pilotes contient un verrou.

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

La routine ObDereferenceObject est similaire à ObDereferenceObjectWithTag, sauf qu’elle ne permet pas à l’appelant d’écrire une balise personnalisée dans un objet. Dans Windows 7 et les versions ultérieures de Windows, ObDereferenceObject écrit toujours une valeur de balise par défaut ('tlfD') dans l’objet. Un appel à ObDereferenceObject a le même effet qu’un appel à ObDereferenceObjectWithTag 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 !obtrace du débogueur en mode noyau. Dans Windows 7, l’extension !obtrace est améliorée pour afficher les balises de référence d’objet, si le suivi de référence d’objet est activé. Par défaut, le suivi des références d’objet est désactivé. Utilisez l’éditeur d’indicateurs globaux (Gflags) pour activer le suivi de référence d’objet. Pour plus d’informations, consultez Suivi de référence d’objet avec des balises.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows 7 et versions ultérieures du système d’exploitation Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport)