EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_CLEANUP callback function

[Applies to KMDF only]

A driver's EvtChildListAddressDescriptionCleanup event callback function frees any memory allocations for an address description that the driver's EvtChildListAddressDescriptionDuplicate callback function allocated.

Syntax


EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_CLEANUP EvtChildListAddressDescriptionCleanup;

VOID EvtChildListAddressDescriptionCleanup(
  _In_    WDFCHILDLIST                          ChildList,
  _Inout_ PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER AddressDescription
)
{ ... }

Parameters

ChildList [in]

A handle to a framework child-list object.

AddressDescription [in, out]

A pointer to a WDF_CHILD_ADDRESS_DESCRIPTION_HEADER structure that identifies an address description.

Return value

None

Remarks

If a bus driver is using dynamic enumeration, it can register an EvtChildListAddressDescriptionCleanup callback function by calling WdfFdoInitSetDefaultChildListConfig or WdfChildListCreate.

If an address description points to additional information that is stored in dynamically allocated memory, and if that memory is allocated by an EvtChildListAddressDescriptionDuplicate callback function, the driver must provide an EvtChildListAddressDescriptionCleanup callback function.

Typically, the EvtChildListAddressDescriptionDuplicate callback function allocates memory by calling ExAllocatePool. The EvtChildListAddressDescriptionCleanup callback function must deallocate that memory by calling ExFreePool. This callback function must not attempt to deallocate the rest of the address description. In other words, the callback function must not deallocate the address description structure that the AddressDescription parameter points to; it must deallocate only additional memory allocations that the description structure points to.

For more information about dynamic enumeration, see Enumerating the Devices on a Bus.

Examples

To define an EvtChildListAddressDescriptionCleanup 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 EvtChildListAddressDescriptionCleanup callback function that is named MyChildListAddressDescriptionCleanup, use the EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_CLEANUP type as shown in this code example:


EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_CLEANUP  MyChildListAddressDescriptionCleanup;

Then, implement your callback function as follows:



_Use_decl_annotations_
VOID
 MyChildListAddressDescriptionCleanup (
    WDFCHILDLIST  ChildList,
    PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER  AddressDescription
    )
  {...}

The EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_CLEANUP function type is defined in the WdfChildlist.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_CHILD_LIST_ADDRESS_DESCRIPTION_CLEANUP 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

Target platform

Universal

Minimum KMDF version

1.0

Header

WdfChildlist.h (include Wdf.h)

IRQL

<= DISPATCH_LEVEL

See also

EvtChildListAddressDescriptionDuplicate
ExAllocatePool
ExFreePool
WDF_CHILD_ADDRESS_DESCRIPTION_HEADER
WdfChildListCreate
WdfFdoInitSetDefaultChildListConfig

 

 

Send comments about this topic to Microsoft

Show: