Fonction ObReferenceObjectByHandleWithTag (wdm.h)

Article
08/08/2023

La routine ObReferenceObjectByHandleWithTag incrémente le nombre de références de l’objet identifié par le handle 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 ObReferenceObjectByHandleWithTag(
  [in]            HANDLE                     Handle,
  [in]            ACCESS_MASK                DesiredAccess,
  [in, optional]  POBJECT_TYPE               ObjectType,
  [in]            KPROCESSOR_MODE            AccessMode,
  [in]            ULONG                      Tag,
  [out]           PVOID                      *Object,
  [out, optional] POBJECT_HANDLE_INFORMATION HandleInformation
);

Paramètres

[in] Handle

Spécifie un handle ouvert pour un objet .

[in] DesiredAccess

Spécifie les types d’accès à l’objet que l’appelant demande. 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. 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

Spécifie le mode d’accès à utiliser pour le case activée d’accès. Il doit être UserMode ou KernelMode. Les pilotes doivent toujours spécifier UserMode pour les handles qu’ils reçoivent de l’espace d’adressage utilisateur.

[in] Tag

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

[out] Object

Pointeur vers une variable dans laquelle la routine écrit un pointeur vers l’objet . Le tableau suivant répertorie les types de pointeurs d’objet qui sont désignés par les valeurs de paramètre ObjectType possibles.

Paramètre ObjectType	Type de pointeur d’objet
*ExEventObjectType	PKEVENT
*ExSemaphoreObjectType	PKSEMAPHORE
*IoFileObjectType	PFILE_OBJECT
*PsProcessType	PEPROCESS ou PKPROCESS
*PsThreadType	PETHREAD ou PKTHREAD
*SeTokenObjectType	PACCESS_TOKEN
*TmEnlistmentObjectType	PKENLISTMENT
*TmResourceManagerObjectType	PKRESOURCEMANAGER
*TmTransactionManagerObjectType	PKTM
*TmTransactionObjectType	PKTRANSACTION

Les structures référencées par les types de pointeurs sont opaques et les pilotes ne peuvent pas accéder aux membres de la structure. Étant donné que les structures sont opaques, PEPROCESS équivaut à PKPROCESS et PETHREAD équivaut à PKTHREAD.

[out, optional] HandleInformation

Les pilotes définissent ce paramètre sur NULL.

Valeur retournée

ObReferenceObjectByHandleWithTag 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 identifié par le paramètre Handle .
STATUS_ACCESS_DENIED	L’appelant ne dispose pas des droits d’accès requis à l’objet.
STATUS_INVALID_HANDLE	Le handle spécifié n’est pas valide.

Remarques

Cette routine effectue la validation d’accès du handle d’objet spécifié. Si l’accès peut être accordé, la routine incrémente le nombre de références d’objets et fournit un pointeur d’objet vers l’appelant. 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’objets, consultez Cycle de vie d’un objet.

ObReferenceObjectByHandleWithTag ne ferme pas ou n’invalide pas le handle d’objet spécifié par le paramètre Handle . Lorsque le handle n’est plus nécessaire, l’appelant peut fermer le handle en appelant la routine ZwClose .

Si la valeur du paramètre AccessMode est KernelMode, l’accès demandé est toujours autorisé. Si AccessMode est UserMode, l’accès demandé est comparé aux droits d’accès de l’appelant à l’objet. Seuls les pilotes de niveau supérieur peuvent spécifier en toute sécurité la valeur UserMode pour le paramètre AccessMode .

À compter de Windows 7, si AccessMode a la valeur KernelMode et que le handle est reçu de l’espace d’adressage de l’utilisateur, le vérificateur de pilotes émet la vérification d’erreur C4, sous-code F6.

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

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 (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport)