ObOpenObjectByPointer function (ntifs.h)

Article
03/16/2022

The ObOpenObjectByPointer function opens an object referenced by a pointer and returns a handle to the object.

Syntax

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

Parameters

[in] Object

Pointer to the object to be opened.

[in] HandleAttributes

Bitmask of flags specifying the desired attributes for the object handle. If the caller is not running in the system process context, these flags must include OBJ_KERNEL_HANDLE. This parameter is optional and can be zero. Otherwise, it is an OR'ed combination of one or more of the following values.

Flag	Meaning
OBJ_EXCLUSIVE	The object is to be opened for exclusive access. If this flag is set and the call to ObOpenObjectByPointer succeeds, the object cannot be shared and cannot be opened again until the handle is closed. This flag is incompatible with the OBJ_INHERIT flag. This flag is invalid for file objects.
OBJ_FORCE_ACCESS_CHECK	All access checks are to be enforced for the object, even if the object is being opened in kernel mode. If this flag is specified, the value of the AccessMode parameter is ignored.
OBJ_INHERIT	The handle can be inherited by child processes of the current process. This flag is incompatible with the OBJ_EXCLUSIVE flag.
OBJ_KERNEL_HANDLE	The handle can only be accessed in kernel mode. This flag must be specified if the caller is not running in the system process context.

[in, optional] PassedAccessState

Pointer to an ACCESS_STATE structure containing the object's subject context, granted access types, and remaining desired access types. This parameter is optional and can be NULL. In a create dispatch routine, this pointer can be found in IrpSp->Parameters.Create.SecurityContext->AccessState, where IrpSp is a pointer to the caller's own stack location in the IRP. (For more information, see IRP_MJ_CREATE.)

[in] DesiredAccess

ACCESS_MASK value specifying the desired access to the object. This parameter is optional and can be zero.

[in, optional] ObjectType

Pointer to the object type. If the value of AccessMode is KernelMode, this parameter is optional and can be NULL. Otherwise, it must be either *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsThreadType, *SeTokenObjectType, or *CmKeyObjectType.

Note

The SeTokenObjectType object type is supported staring with Windows XP and the CmKeyObjectType object type is supported staring with Windows 7.

[in] AccessMode

Access mode to be used for the access check. This parameter is required and must be either UserMode or KernelMode:

If AccessMode is KernelMode, the system always allows the requested access regardless of any restricted access previously set a driver (for example, access restricted in a prior call to POB_PRE_OPERATION_CALLBACK callback).
If AccessMode is UserMode, the requested access is compared to the granted access for the object.

[out] Handle

Pointer to a caller-allocated variable that receives a handle to the object.

Return value

ObOpenObjectByPointer returns STATUS_SUCCESS or an appropriate NTSTATUS value such as one of the following:

Return code	Description
STATUS_ACCESS_DENIED	The caller did not have the required access to open a handle for the object. This is an error code.
STATUS_INSUFFICIENT_RESOURCES	ObOpenObjectByPointer encountered a pool allocation failure. This is an error code.
STATUS_INVALID_PARAMETER	An invalid flag value was specified in the HandleAttributes parameter. This is an error code.
STATUS_OBJECT_TYPE_MISMATCH	The object pointed to by the Object parameter was not of the type specified in the ObjectType parameter. This is an error code.
STATUS_PRIVILEGE_NOT_HELD	The caller did not have the required privilege to create a handle with the access specified in the DesiredAccess parameter. This is an error code.
STATUS_QUOTA_EXCEEDED	The caller is running in the context of a process whose memory quota is not sufficient to allocate the object handle. This is an error code.
STATUS_UNSUCCESSFUL	The object handle could not be created. This is an error code.

Remarks

If the Object parameter points to a file object (that is, a FILE_OBJECT structure), ObOpenObjectByPointer can only be called after at least one handle has been created for the file object. Callers can check the Flags member of the FILE_OBJECT structure that the Object parameter points to. If the FO_HANDLE_CREATED flag is set, this means that one or more handles have been created for the file object, so it is safe to call ObOpenObjectByPointer.

Any handle obtained by calling ObOpenObjectByPointer must eventually be released by calling ZwClose.

Driver routines that run in a process context other than that of the system process must set the OBJ_KERNEL_HANDLE flag in the HandleAttributes parameter. This restricts the use of the handle returned by ObOpenObjectByPointer to processes running in kernel mode. Otherwise, the handle can be accessed by the process in whose context the driver is running.

Requirements

Requirement	Value
Target Platform	Universal
Header	ntifs.h (include Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL