ObDereferenceObject macro (wdm.h)

Article
02/22/2024

The ObDereferenceObject routine decrements the given object's reference count and performs retention checks.

Syntax

void ObDereferenceObject(
  [in]  a
);

Parameters

[in] a

Pointer to the object's body.

Return value

None

Remarks

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

ObDereferenceObject decreases the reference count of an object by one. If the object was created as temporary (the OBJ_PERMANENT flag was not specified on creation), and the reference count reaches zero, the object can be deleted by the system.

A driver can delete a temporary object it created by decreasing its reference count to zero. A driver must never attempt to delete an object 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 a reference count of one, so it is not deleted when the driver dereferences it. A driver can only delete a permanent object it created by using the ZwMakeTemporaryObject routine to make it temporary. Use the following steps to delete a permanent object that you created:

Call ObDereferenceObject.
Call the appropriate ZwOpenXxx or ZwCreateXxx routine to get a handle for the object, if necessary.
Call ZwMakeTemporaryObject with the handle obtained in step 2.
Call ZwClose with the handle obtained in step 2.

Use ObDereferenceObjectDeferDelete instead of ObDereferenceObject for any object, particularly Kernel Transaction Manager (KTM) objects, when the immediate deletion by the current thread of the object (by using ObDereferenceObject) might result in a deadlock.

Requirements

Requirement	Value
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL
DDI compliance rules	HwStorPortProhibitedDDIs(storport)