ObReferenceObjectByHandle

NTSTATUS
ObReferenceObjectByHandle(
IN HANDLE Handle,
IN ACCESS_MASK DesiredAccess,
IN POBJECT_TYPE ObjectType, /* optional */
IN KPROCESSOR_MODE AccessMode,
OUT PVOID *Object,
OUT POBJECT_HANDLE_INFORMATION HandleInformation /* optional */
);

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

Parameters

Handle: Specifies an open handle for an object.
DesiredAccess: Specifies the requested types of access to the object. The interpretation of this field is dependent on the object type.
ObjectType: Points to the object type structure for the object’s type (optional).
AccessMode: Specifies the access mode to use for the access check. It must be either UserMode or KernelMode. Lower-level drivers should specify KernelMode.
Object: Points to a variable that receives a pointer to the object’s body.
HandleInformation: Points to a structure that receives the handle attributes and the granted access rights for the object.

Return Value

ObReferenceObjectByHandle can return one of the following status codes:

STATUS_SUCCESS
STATUS_OBJECT_TYPE_MISMATCH
STATUS_ACCESS_DENIED
STATUS_INVALID_HANDLE

Comments

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 the AccessMode parameter is KernelMode, the requested access is always allowed. If AccessMode is UserMode, the requested access is compared to the granted access for the object. Only highest-level drivers can safely specify UserMode for the input AccessMode.

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.

Callers of this function must be running at IRQL PASSIVE_LEVEL.