Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

ObReferenceObjectByHandle routine

The ObReferenceObjectByHandle routine provides access validation on the object handle, and, if access can be granted, returns the corresponding pointer to the object's body.

Syntax


NTSTATUS ObReferenceObjectByHandle(
  _In_       HANDLE Handle,
  _In_       ACCESS_MASK DesiredAccess,
  _In_opt_   POBJECT_TYPE ObjectType,
  _In_       KPROCESSOR_MODE AccessMode,
  _Out_      PVOID *Object,
  _Out_opt_  POBJECT_HANDLE_INFORMATION HandleInformation
);

Parameters

Handle [in]

Specifies an open handle for an object.

DesiredAccess [in]

Specifies the requested types of access to the object. The interpretation of this field is dependent on the object type. Do not use any generic access rights. For more information, see ACCESS_MASK.

ObjectType [in, optional]

Pointer to the object type. ObjectType can be *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType, or *TmTransactionObjectType.

Note  The SeTokenObjectType object type is supported starting with Windows XP.

If ObjectType is not NULL, the operating system verifies that the supplied object type matches the object type of the object that Handle specifies.

AccessMode [in]

Specifies the access mode to use for the access check. It must be either UserMode or KernelMode. Drivers should always specify UserMode for handles they receive from user address space.

Object [out]

Pointer to a variable that receives a pointer to the object's body. The following table contains the pointer types.

ObjectType parameterObject pointer type

*ExEventObjectType

PKEVENT

*ExSemaphoreObjectType

PKSEMAPHORE

*IoFileObjectType

PFILE_OBJECT

*PsProcessType

PEPROCESS or PKPROCESS

*PsThreadType

PETHREAD or PKTHREAD

*SeTokenObjectType

PACCESS_TOKEN

*TmEnlistmentObjectType

PKENLISTMENT

*TmResourceManagerObjectType

PKRESOURCEMANAGER

*TmTransactionManagerObjectType

PKTM

*TmTransactionObjectType

PKTRANSACTION

 

The structures that the pointer types reference are opaque, and drivers cannot access the structure members. Because the structures are opaque, PEPROCESS is equivalent to PKPROCESS, and PETHREAD is equivalent to PKTHREAD.

Note  The SeTokenObjectType object type is supported starting with Windows XP.

HandleInformation [out, optional]

Drivers set this to NULL.

Return value

ObReferenceObjectByHandle returns STATUS_SUCCESS if the call is successful. Possible return values include the following error codes:

Return codeDescription
STATUS_OBJECT_TYPE_MISMATCH

The ObjectType parameter specifies the wrong object type for the object that is identified by the Handle parameter.

STATUS_ACCESS_DENIED

The caller cannot be granted the requested access rights to the object.

STATUS_INVALID_HANDLE

The Handle parameter is not a valid object handle.

 

Remarks

A pointer to the object body is retrieved from the object table entry and returned to the caller by means of the Object parameter.

If AccessMode is UserMode, the requested access is compared to the granted access for the object. If AccessMode is KernelMode, the handle should originate in the kernel address space.

Starting with Windows 7, if AccessMode is KernelMode and handle is received from user address space, Driver Verifier issues bugcheck C4, subcode F6.

If the call succeeds, a pointer to the object body is returned to the caller and the pointer reference count is incremented. Incrementing this count prevents the object from being deleted while the pointer is being referenced. The caller must decrement the reference count with ObDereferenceObject as soon as it is done with the object.

Requirements

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

PASSIVE_LEVEL

DDI compliance rules

IrqlObPassive, TargetRelationNeedsRef, HwStorPortProhibitedDDIs

See also

ACCESS_MASK
ObDereferenceObject
ObReferenceObject
ObReferenceObjectByPointer

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft