EvtDestroyCallback function

[Applies to KMDF and UMDF]

A driver's EvtDestroyCallback event callback function performs operations that are associated with the deletion of a framework object.

Syntax


EVT_WDF_OBJECT_CONTEXT_DESTROY EvtDestroyCallback;

VOID EvtDestroyCallback(
  _In_  WDFOBJECT Object
)
{ ... }

Parameters

Object [in]

A handle to a framework object.

Return value

None

Remarks

The driver can specify an EvtDestroyCallback callback function in a WDF_OBJECT_ATTRIBUTES structure. This structure is used as input to all of the framework methods that create framework objects, such as WdfDeviceCreate.

The framework calls the EvtDestroyCallback callback function after the object's reference count has been decremented to zero. The framework deletes the object immediately after the EvtDestroyCallback callback function returns.

The EvtDestroyCallback can access the object context but cannot call any methods on the object.

If a driver supplies both an EvtCleanupCallback callback function and an EvtDestroyCallback callback function for a object, the framework calls the EvtCleanupCallback callback function first.

When an object is deleted, the framework also deletes the object's children. The framework calls the child objects' EvtCleanupCallback callback functions before calling the parent object's EvtCleanupCallback callback function. Next, if the child's reference count is zero, the framework calls the child object's EvtDestroyCallback callback function. Finally, if the parent's reference count is zero, the framework calls the parent object's EvtDestroyCallback callback function.

When a driver creates an object, it sometimes allocates object-specific memory buffers and stores the buffer pointers in the object's context space. The driver's EvtCleanupCallback or EvtDestroyCallback callback function can deallocate these memory buffers.

For more information about deleting framework objects, see Framework Object Life Cycle.

Typically, the framework calls the EvtDestroyCallback callback function at IRQL <= DISPATCH_LEVEL. However, the framework calls the callback function at IRQL = PASSIVE_LEVEL in the following situations:

  • The object's handle type is WDFDEVICE, WDFDRIVER, WDFDPC, WDFINTERRUPT, WDFIOTARGET, WDFQUEUE, WDFSTRING, WDFTIMER, or WDFWORKITEM.

  • The object's handle type is WDFMEMORY or WDFLOOKASIDE, and the driver has specified PagedPool for the PoolType parameter to WdfMemoryCreate or WdfLookasideListCreate.

Beginning with version 1.9 of the framework, the wdfroletypes.h header file contains some alternative, object type-specific, function types for the EvtDestroyCallback callback function. These alternative types help verification tools to determine whether the driver is properly using the callback function. Use the following table to determine which function type to use.

Object TypeFunction Type

Device object

EVT_WDF_DEVICE_CONTEXT_DESTROY

I/O queue object

EVT_WDF_IO_QUEUE_CONTEXT_DESTROY_CALLBACK

File object

EVT_WDF_FILE_CONTEXT_DESTROY_CALLBACK

All other objects

EVT_WDF_OBJECT_CONTEXT_DESTROY

 

Examples

To define an EvtDestroyCallback callback function, you must first provide a function declaration that identifies the type of callback function you’re defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it’s a requirement for writing drivers for the Windows operating system.

For example, to define an EvtDestroyCallback callback function that is named MyDestroyCallback, use the EVT_WDF_OBJECT_CONTEXT_DESTROY type as shown in this code example:


EVT_WDF_OBJECT_CONTEXT_DESTROY MyDestroyCallback;

Then, implement your callback function as follows:


_Use_decl_annotations_
VOID 
  MyDestroyCallback (
    WDFOBJECTObject
    )
  {...}

The EVT_WDF_OBJECT_CONTEXT_DESTROY function type is defined in the Wdfobject.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the EVT_WDF_OBJECT_CONTEXT_DESTROY function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Minimum KMDF version

1.0

Minimum UMDF version

2.0

Header

Wdfobject.h (include Wdf.h)

IRQL

See Remarks section.

See also

WDF_OBJECT_ATTRIBUTES
EvtCleanupCallback

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft