ObReferenceObjectByPointer

The ObReferenceObjectByPointer routine increments the pointer reference count for a given object.

NTSTATUS 
  ObReferenceObjectByPointer(
    IN PVOID  Object,
    IN ACCESS_MASK  DesiredAccess,
    IN POBJECT_TYPE  ObjectType,
    IN KPROCESSOR_MODE  AccessMode
    );

Parameters

Object

Pointer to the object’s body.

DesiredAccess

Specifies a mask representing the requested access to the object.

ObjectType

Pointer to the object type. ObjectType can be either *IoFileObjectType or *ExEventObjectType. This parameter can also be NULL if AccessMode is KernelMode.

AccessMode

Indicates the access mode to use for the access check. It must be either UserMode or KernelMode. Lower-level drivers should specify KernelMode.

Return Value

ObReferenceObjectByPointer returns an NTSTATUS value. Possible return values include:

STATUS_SUCCESS
STATUS_OBJECT_TYPE_MISMATCH

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

Calling this routine prevents the object from being deleted, possibly by another component’s call to ObDereferenceObject or ZwClose. The caller must decrement the reference count with ObDereferenceObject as soon as it is done with the object.

Callers of ObReferenceObjectByPointer must be running at IRQL <= DISPATCH_LEVEL.

See Also

ObDereferenceObject, ObReferenceObject, ObReferenceObjectByHandle, ZwClose