The ObDereferenceObjectWithTag routine decrements the reference count of the specified object, and writes a four-byte tag value to the object to support object reference tracing.
VOID ObDereferenceObjectWithTag( _In_ PVOID Object, _In_ ULONG Tag );
A kernel-mode driver calls this routine to decrement the reference count of an object by one. If the object was created as temporary (that is, the OBJ_PERMANENT flag was not specified when the object was created), and the reference count reaches zero, the object manager deletes 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.
An object is permanent if it was created with the OBJ_PERMANENT object attribute flag specified. (For more information about object attributes, see InitializeObjectAttributes.) A permanent object is created with an initial reference count of one, so the object is not deleted when the driver removes its last reference to the object.
To prepare a permanent object to be deleted, a driver can call the ZwMakeTemporaryObject routine to make the object temporary. A driver should only delete a permanent object that it created. Use the following steps to delete a permanent object:
Get the handle to the object. If necessary, call the appropriate ZwOpenXxx or ZwCreateXxx routine to get the object handle.
Call ZwMakeTemporaryObject with the handle obtained in step 2.
Call ZwClose with the handle obtained in step 2.
For example, such a deadlock can occur if ObDereferenceObjectWithTag is used to dereference a Kernel Transaction Manager (KTM) object when a higher-level driver on the driver stack is holding a lock.
For more information about object references, see Life Cycle of an Object.
The ObDereferenceObject routine is similar to ObDereferenceObjectWithTag, except that it does not enable the caller to write a custom tag to an object. In Windows 7 and later versions of Windows, ObDereferenceObject always writes a default tag value ('tlfD') to the object. A call to ObDereferenceObject has the same effect as a call to ObDereferenceObjectWithTag 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.
|Windows version||Available in Windows 7 and later versions of the Windows operating system.|
|Header||wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)|
|DDI compliance rules||HwStorPortProhibitedDDIs|