ObOpenObjectByPointer, fonction (ntifs.h)

Article
07/02/2025

La fonction ObOpenObjectByPointer ouvre un objet référencé par un pointeur et retourne un handle à l’objet.

Syntaxe

NTSTATUS ObOpenObjectByPointer(
  [in]           PVOID           Object,
  [in]           ULONG           HandleAttributes,
  [in, optional] PACCESS_STATE   PassedAccessState,
  [in]           ACCESS_MASK     DesiredAccess,
  [in, optional] POBJECT_TYPE    ObjectType,
  [in]           KPROCESSOR_MODE AccessMode,
  [out]          PHANDLE         Handle
);

Paramètres

[in] Object

Pointeur vers l’objet à ouvrir.

[in] HandleAttributes

Masque de bits des indicateurs spécifiant les attributs souhaités pour le handle d’objet. Si l’appelant n’est pas en cours d’exécution dans le contexte du processus système, ces indicateurs doivent inclure OBJ_KERNEL_HANDLE. Ce paramètre est facultatif et peut être égal à zéro. Sinon, il s’agit d’une combinaison OR’ed d’une ou plusieurs des valeurs suivantes.

Drapeau	Signification
OBJ_EXCLUSIVE	L’objet doit être ouvert pour un accès exclusif. Si cet indicateur est défini et que l’appel à ObOpenObjectByPointer réussit, l’objet ne peut pas être partagé et ne peut pas être ouvert à nouveau tant que le handle n’est pas fermé. Cet indicateur n’est pas compatible avec l’indicateur OBJ_INHERIT. Cet indicateur n’est pas valide pour les objets de fichier.
OBJ_FORCE_ACCESS_CHECK	Toutes les vérifications d’accès doivent être appliquées pour l’objet, même si l’objet est ouvert en mode noyau. Si cet indicateur est spécifié, la valeur du paramètre AccessMode est ignorée.
OBJ_INHERIT	Le handle peut être hérité par les processus enfants du processus actuel. Cet indicateur n’est pas compatible avec l’indicateur OBJ_EXCLUSIVE.
OBJ_KERNEL_HANDLE	Le handle est accessible uniquement en mode noyau. Cet indicateur doit être spécifié si l’appelant n’est pas en cours d’exécution dans le contexte du processus système.

[in, optional] PassedAccessState

Pointeur vers une structure ACCESS_STATE contenant le contexte de l’objet de l’objet, les types d’accès accordés et les types d’accès souhaités restants. Ce paramètre est facultatif et peut être NULL. Dans une routine de distribution de création, ce pointeur se trouve dans IrpSp->Parameters.Create.SecurityContext->AccessState, où IrpSp est un pointeur vers le propre emplacement de pile de l’appelant dans l’IRP. (Pour plus d’informations, consultez IRP_MJ_CREATE.)

[in] DesiredAccess

ACCESS_MASK valeur spécifiant l’accès souhaité à l’objet. Ce paramètre est facultatif et peut être égal à zéro.

[in, optional] ObjectType

Pointeur vers le type d’objet. Si la valeur de AccessMode est KernelMode, ce paramètre est facultatif et peut être NULL. Sinon, il doit être *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsThreadType, *SeTokenObjectTypeou *CmKeyObjectType.

Notes

Le type d’objet SeTokenObjectType est pris en charge avec Windows XP et le type d’objet CmKeyObjectType est pris en charge avec Windows 7.

[in] AccessMode

Mode d’accès à utiliser pour la vérification d’accès. Ce paramètre est obligatoire et doit être UserMode ou KernelMode:

Si AccessMode est kernelMode, le système autorise toujours l’accès demandé, quel que soit l’accès restreint précédemment défini par un pilote (par exemple, accès restreint dans un appel antérieur à POB_PRE_OPERATION_CALLBACK rappel).
Si AccessMode est UserMode, l’accès demandé est comparé à l’accès accordé pour l’objet.

[out] Handle

Pointeur vers une variable allouée par l’appelant qui reçoit un handle vers l’objet.

Valeur de retour

ObOpenObjectByPointer retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, telle que l’une des suivantes :

Retourner le code	Description
STATUS_ACCESS_DENIED	L’appelant n’a pas l’accès requis pour ouvrir un handle pour l’objet. Il s’agit d’un code d’erreur.
STATUS_INSUFFICIENT_RESOURCES	ObOpenObjectByPointer a rencontré un échec d’allocation de pool. Il s’agit d’un code d’erreur.
STATUS_INVALID_PARAMETER	Une valeur d’indicateur non valide a été spécifiée dans le paramètre HandleAttributes. Il s’agit d’un code d’erreur.
STATUS_OBJECT_TYPE_MISMATCH	L’objet pointé par le paramètre Object n’était pas du type spécifié dans le paramètre ObjectType. Il s’agit d’un code d’erreur.
STATUS_PRIVILEGE_NOT_HELD	L’appelant n’a pas le privilège requis pour créer un handle avec l’accès spécifié dans le paramètre DesiredAccess. Il s’agit d’un code d’erreur.
STATUS_QUOTA_EXCEEDED	L’appelant s’exécute dans le contexte d’un processus dont le quota de mémoire n’est pas suffisant pour allouer le handle d’objet. Il s’agit d’un code d’erreur.
STATUS_UNSUCCESSFUL	Impossible de créer le handle d’objet. Il s’agit d’un code d’erreur.

Remarques

Si le paramètre Object pointe vers un objet de fichier (autrement dit, une structure FILE_OBJECT), ObOpenObjectByPointer ne peut être appelé qu’après avoir créé au moins un handle pour l’objet de fichier. Les appelants peuvent vérifier les indicateurs membre de la structure FILE_OBJECT vers laquelle pointe le paramètre Object. Si l’indicateur FO_HANDLE_CREATED est défini, cela signifie qu’un ou plusieurs handles ont été créés pour l’objet de fichier. Il est donc sûr d’appeler ObOpenObjectByPointer.

Tout handle obtenu en appelant ObOpenObjectByPointer doit finalement être libéré en appelant ZwClose.

Les routines de pilote qui s’exécutent dans un contexte de processus autre que celui du processus système doivent définir l’indicateur de OBJ_KERNEL_HANDLE dans le paramètre HandleAttributes. Cela limite l’utilisation du handle retourné par ObOpenObjectByPointer aux processus s’exécutant en mode noyau. Sinon, le handle est accessible par le processus dans lequel le pilote est en cours d’exécution.