ObDereferenceObject

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

None

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

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

Callers of ObDereferenceObject must be running at IRQL <= DISPATCH_LEVEL.

See Also

InitializeObjectAttributes, ZwClose, ZwMakeTemporaryObject