Export (0) Print
Expand All

ObReferenceObjectWithTag routine

The ObReferenceObjectWithTag routine increments the reference count of the specified object, and writes a four-byte tag value to the object to support object reference tracing.

Syntax


VOID ObReferenceObjectWithTag(
  _In_  PVOID Object,
  _In_  ULONG Tag
);

Parameters

Object [in]

A pointer to the object. The caller obtains this pointer either when it creates the object, or from a previous call to the ObReferenceObjectByHandleWithTag routine after it opens the object.

Tag [in]

Specifies a four-byte, custom tag value. For more information, see the following Remarks section.

Return value

ObReferenceObjectWithTag returns a value that is reserved for system use. Drivers must treat this value as VOID.

Remarks

ObReferenceObjectWithTag simply increments the pointer reference count for an object, without making any access checks on the specified object. In contrast, the ObReferenceObjectByHandleWithTag and ObReferenceObjectByPointerWithTag routines verify that the caller has the required access rights to the object and fail if the caller does not have these rights.

A ObReferenceObjectWithTag call prevents deletion of the specified object at least until the driver either calls the ObDereferenceObjectWithTag routine, or closes the object. After the object is no longer needed, the driver must call ObDereferenceObjectWithTag to remove its reference to the object.

When the reference count for an object reaches zero, a kernel-mode component can delete the object. However, a driver can delete only those objects that it created, and a driver should never attempt to delete any object that it did not create.

For more information about object references, see Life Cycle of an Object.

The ObReferenceObject routine is similar to ObReferenceObjectWithTag, except that it does not enable the caller to write a custom tag to an object. In Windows 7 and later versions of Windows, ObReferenceObject always writes a default tag value ('tlfD') to the object. A call to ObReferenceObject has the same effect as a call to ObReferenceObjectWithTag that specifies Tag = 'tlfD'.

To view an object reference trace in the Windows debugging tools, use the !obtrace kernel-mode debugger extension. In Windows 7, the !obtrace extension is enhanced to display object reference tags, if object reference tracing is enabled. By default, object reference tracing is turned off. Use the Global Flags Editor (Gflags) to enable object reference tracing. For more information, see Object Reference Tracing with Tags.

Requirements

Version

Available in Windows 7 and later versions of the Windows operating system.

Header

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

Library

Ntoskrnl.lib

IRQL

<= DISPATCH_LEVEL

DDI compliance rules

HwStorPortProhibitedDDIs

See also

ObDereferenceObjectWithTag
ObReferenceObject
ObReferenceObjectByHandleWithTag
ObReferenceObjectByPointerWithTag

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft