Fonction ObReferenceObjectByPointerWithTag (wdm.h)

Article
02/29/2024

La routine ObReferenceObjectByPointerWithTag 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

NTSTATUS ObReferenceObjectByPointerWithTag(
  [in]           PVOID           Object,
  [in]           ACCESS_MASK     DesiredAccess,
  [in, optional] POBJECT_TYPE    ObjectType,
  [in]           KPROCESSOR_MODE AccessMode,
  [in]           ULONG           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] DesiredAccess

Spécifie les types d’accès à l’objet demandé par l’appelant. Ce paramètre est un masque de bits de type ACCESS_MASK. L’interprétation de ce champ dépend du type d’objet. N’utilisez aucun droit d’accès générique.

[in, optional] ObjectType

Pointeur vers une structure opaque qui spécifie le type d’objet. Ce paramètre pointe vers une structure OBJECT_TYPE . Définissez ObjectType sur NULL ou sur l’une des valeurs de pointeur suivantes, qui sont déclarées dans le fichier d’en-tête Wdm.h : *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType ou *TmTransactionObjectType. Ce paramètre peut avoir la valeur NULL si AccessMode est KernelMode. Si ObjectType n’a pas la valeur NULL, la routine vérifie que le type d’objet fourni correspond au type d’objet de l’objet spécifié par le paramètre Handle .

[in] AccessMode

Indique le mode d’accès à utiliser pour le case activée d’accès. Définissez ce paramètre sur l’une des valeurs d’énumération MODE suivantes :

Usermode
KernelMode

Les pilotes de niveau inférieur doivent spécifier KernelMode.

[in] Tag

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

Valeur retournée

ObReferenceObjectByPointerWithTag retourne STATUS_SUCCESS si l’appel réussit. Les valeurs de retour d’erreur possibles sont les suivantes :

Code de retour	Description
STATUS_OBJECT_TYPE_MISMATCH	Le paramètre ObjectType spécifie le type d’objet incorrect pour l’objet vers lequel pointe le paramètre Object , ou ObjectType a la valeur NULL , mais AccessMode est UserMode.

Remarques

Cette routine valide l’accès à l’objet spécifié. Si l’accès peut être accordé, la routine incrémente le nombre de références d’objets. Cet incrément empêche la suppression de l’objet pendant que l’appelant utilise l’objet. Lorsque l’objet n’est plus nécessaire, l’appelant doit décrémenter le nombre de références en appelant la routine ObDereferenceObjectWithTag ou ObDereferenceObjectDeferDeleteWithTag .

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

La routine ObReferenceObjectByPointer est similaire à ObReferenceObjectByPointerWithTag, 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, ObReferenceObjectByPointer écrit toujours une valeur de balise par défaut ('tlfD') dans l’objet. Un appel à ObReferenceObjectByPointer a le même effet qu’un appel à ObReferenceObjectByPointerWithTag 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	Universal
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)