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