WdfObjectReferenceWithTag macro

Article
03/01/2023

[Applies to KMDF and UMDF]

The WdfObjectReferenceWithTag macro increments the reference count for a specified framework object and assigns the driver's current file name and line number to the reference. The macro also assigns a tag value to the reference.

Syntax

VOID WdfObjectReferenceWithTag(
  [in] WDFOBJECT Handle,
  [in] PVOID     Tag
);

Parameters

Handle [in]
A handle to a framework object.

Tag [in]
A driver-defined value that the framework stores as an identification tag for the object reference.

Return value

None.

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

Remarks

If your driver calls WdfObjectReferenceWithTag to increment a reference count, the driver must call WdfObjectDereferenceWithTag to decrement the count.

Calling WdfObjectReferenceActual or WdfObjectReferenceWithTag instead of WdfObjectReference provides additional information (tag value, line number, and file name) to Microsoft debuggers. WdfObjectReferenceActual allows your driver to specify the line number and file name, while WdfObjectReferenceWithTag 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 about debugger extensions, see Debugging a KMDF Driver.

For more information about object reference counts, see Framework Object Life Cycle.

Examples

The following code example increments an object's reference count and assigns a tag value to the reference.

WdfObjectReferenceWithTag(
                          object,
                          pTag
                          );

Requirements

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

Share via