Fonction ObReferenceObjectByHandle (wdm.h)

La routine ObReferenceObjectByHandle permet de valider l’accès sur le handle d’objet et, si l’accès peut être accordé, retourne le pointeur correspondant vers le corps de l’objet.

Syntaxe

NTSTATUS ObReferenceObjectByHandle(
  [in]            HANDLE                     Handle,
  [in]            ACCESS_MASK                DesiredAccess,
  [in, optional]  POBJECT_TYPE               ObjectType,
  [in]            KPROCESSOR_MODE            AccessMode,
  [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 demandés à l’objet. L’interprétation de ce champ dépend du type d’objet. N’utilisez aucun droit d’accès générique. Pour plus d’informations, consultez ACCESS_MASK.

[in, optional] ObjectType

Pointeur vers le type d’objet. ObjectType peut être *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType ou *TmTransactionObjectType.

Si ObjectType n’a pas la valeur NULL, le système d’exploitation vérifie que le type d’objet fourni correspond au type d’objet de l’objet spécifié par 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.

[out] Object

Pointeur vers une variable qui reçoit un pointeur vers le corps de l’objet. Le tableau suivant contient les types de pointeurs.

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 pointeur 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 cette valeur sur NULL.

Valeur retournée

ObReferenceObjectByHandle retourne STATUS_SUCCESS si l’appel réussit. Les valeurs de retour possibles incluent les codes d’erreur suivants :

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 Impossible d’accorder à l’appelant les droits d’accès demandés à l’objet.
STATUS_INVALID_HANDLE Le paramètre Handle n’est pas un handle d’objet valide.

Remarques

Un pointeur vers le corps de l’objet est récupéré à partir de l’entrée de la table d’objets et renvoyé à l’appelant au moyen du paramètre Object .

Si AccessMode est UserMode, l’accès demandé est comparé à l’accès accordé pour l’objet. Si AccessMode est KernelMode, le handle doit provenir de l’espace d’adressage du noyau.

À compter de Windows 7, si AccessMode est KernelMode et que le handle est reçu à partir de l’espace d’adressage utilisateur, driver Verifier émet la vérification de bogue C4, sous-code F6.

Si l’appel réussit, un pointeur vers le corps de l’objet est retourné à l’appelant et le nombre de références du pointeur est incrémenté. L’incrémentation de ce nombre empêche la suppression de l’objet pendant que le pointeur est référencé. L’appelant doit décrémenter le nombre de références avec ObDereferenceObject dès qu’il a terminé avec l’objet.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Disponible à partir de Windows 2000.
Plateforme cible Universal
En-tête wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
Règles de conformité DDI HwStorPortProhibitedDDIs(storport),IrqlObPassive(wdm), TargetRelationNeedsRef(wdm)

Voir aussi

ACCESS_MASK

ObDereferenceObject

ObReferenceObject

ObReferenceObjectByPointer