WdfObjectDereferenceActual function (wdfobject.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfObjectDereferenceActual method decrements the reference count for a specified framework object and assigns a tag value, line number, and file name to the reference.

Syntax

void WdfObjectDereferenceActual(
  [in]           WDFOBJECT Handle,
  [in, optional] PVOID     Tag,
  [in]           LONG      Line,
  [in, optional] PCCH      File
);

Parameters

[in] Handle

A handle to a framework object.

[in, optional] Tag

A driver-defined value that identifies an object reference. The tag value must match a tag value that the driver previously supplied to WdfObjectReferenceActual.

[in] Line

A numeric value that represents a line number in a driver source file.

[in, optional] File

A pointer to a null-terminated constant character string that represents the name of a driver source file. This parameter is optional and can be NULL.

Return value

None

Remarks

A bug check occurs if the driver supplies an invalid object handle.

If the object's reference count becomes zero, the object might be deleted before WdfObjectDereferenceActual returns.

Calling WdfObjectDereferenceActual or WdfObjectDereferenceWithTag instead of WdfObjectDereference provides additional information (tag string, line number, and file name) to Microsoft debuggers. WdfObjectDereferenceActual allows your driver to specify the line number and file name, while WdfObjectDereferenceWithTag uses the driver's current line number and file name.

You can view the tag, line number, and file name values by using the !wdftagtracker debugger extension. The debugger extension displays the tag value as both a pointer and a series of characters. For more information about debugger extensions, see Debugging a KMDF Driver.

For more information about object reference counts and the cleanup rules for a framework object hierarchy, see Framework Object Life Cycle.

Examples

The following code example decrements an object's reference count and assigns a tag value, line number, and file name to the reference.

WdfObjectDereferenceActual(
                           object,
                           pTag,
                           line,
                           FILE_NAME
                           );

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfobject.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf)

Share via