ObReferenceObjectByPointer routine

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

Syntax


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

Parameters

Object [in]

Pointer to the object's body.

DesiredAccess [in]

Specifies a mask representing the requested access to the object.

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 in Windows XP and later versions of Windows.
 

This parameter can also be NULL if AccessMode is KernelMode.

AccessMode [in]

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

Remarks

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.

Requirements

Target platform

Universal

Version

Available starting with Windows 2000.

Header

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

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

<= DISPATCH_LEVEL

DDI compliance rules

TargetRelationNeedsRef, HwStorPortProhibitedDDIs

See also

ObDereferenceObject
ObReferenceObject
ObReferenceObjectByHandle
ZwClose

 

 

Send comments about this topic to Microsoft

Show: