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

VOID 
  ObDereferenceObject(
    IN PVOID  Object
    );

Parameters

Object

Pointer to the object's body.

Return Value

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

Comments

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. (See InitializeObjectAttributes For more information about object attributes.) 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:

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

Important.  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

IRQL: <= DISPATCH_LEVEL

Headers: Declared in Wdm.h. Include Wdm.h, Ntddk.h, Ntifs.h, or Fltkernel.h.

See Also

ObDereferenceObjectDeferDelete, IoGetDeviceObjectPointer, InitializeObjectAttributes, ZwClose, ZwMakeTemporaryObject