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) |