Skip to content

Latest commit

 

History

History
111 lines (76 loc) · 4.2 KB

nf-wdfobject-wdfobjectdereferenceactual.md

File metadata and controls

111 lines (76 loc) · 4.2 KB
Raw
UID title description old-location tech.root ms.date keywords ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames f1_keywords topic_type api_type api_location api_name
NF:wdfobject.WdfObjectDereferenceActual
WdfObjectDereferenceActual function (wdfobject.h)
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.
wdf\wdfobjectdereferenceactual.htm
wdf
02/26/2018
WdfObjectDereferenceActual function
DFGenObjectRef_d09786da-bccf-4735-bd7b-816bf2bd999d.xml, WdfObjectDereferenceActual, WdfObjectDereferenceActual method, kmdf.wdfobjectdereferenceactual, wdf.wdfobjectdereferenceactual, wdfobject/WdfObjectDereferenceActual
wdfobject.h
Wdf.h
Universal
1.0
2.0
DriverCreate
Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
<=DISPATCH_LEVEL
Windows
WdfObjectDereferenceActual
wdfobject/WdfObjectDereferenceActual
APIRef
kbSyntax
LibDef
Wdf01000.sys
Wdf01000.sys.dll
WUDFx02000.dll
WUDFx02000.dll.dll
WdfObjectDereferenceActual

WdfObjectDereferenceActual function

-description

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

-parameters

-param Handle [in]

A handle to a framework object.

-param Tag [in, optional]

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

-param Line [in]

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

-param File [in, optional]

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.

-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
                           );

-see-also

WdfObjectDereference

WdfObjectReferenceActual