Fonction ObReferenceObjectByPointerWithTag (wdm.h)
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) |