ObReferenceObjectByHandle 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.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 ); 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 Pointer to the object type. ObjectType can be either *IoFileObjectType or *ExEventObjectType. This parameter can also be NULL if AccessMode is KernelMode. 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 Pointer to a variable that receives a pointer to the object’s body. HandleInformation Drivers set this to NULL. Return Value ObReferenceObjectByHandle returns an NTSTATUS value. The possible return values include:STATUS_SUCCESS STATUS_OBJECT_TYPE_MISMATCH STATUS_ACCESS_DENIED STATUS_INVALID_HANDLEHeaders Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.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. The caller must decrement the reference count with ObDereferenceObject as soon as it is done with the object. Callers of ObReferenceObjectByHandle must be running at IRQL = PASSIVE_LEVEL.
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.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
);
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
Pointer to the object type. ObjectType can be either *IoFileObjectType or *ExEventObjectType. This parameter can also be NULL if AccessMode is KernelMode.
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
Pointer to a variable that receives a pointer to the object’s body.
HandleInformation
Drivers set this to NULL.
Return Value
ObReferenceObjectByHandle returns an NTSTATUS value. The possible return values include:STATUS_SUCCESS
STATUS_OBJECT_TYPE_MISMATCH
STATUS_ACCESS_DENIED
STATUS_INVALID_HANDLEHeaders
Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.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. The caller must decrement the reference count with ObDereferenceObject as soon as it is done with the object. Callers of ObReferenceObjectByHandle must be running at IRQL = PASSIVE_LEVEL.