EvtChildListIdentificationDescriptionCleanup function

[Applies to KMDF only]

A driver's EvtChildListIdentificationDescriptionCleanup event callback function frees any memory allocations for an identification description that the driver's EvtChildListIdentificationDescriptionDuplicate callback function allocated.

Syntax


EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_CLEANUP EvtChildListIdentificationDescriptionCleanup;

VOID EvtChildListIdentificationDescriptionCleanup(
  _In_     WDFCHILDLIST ChildList,
  _Inout_  PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription
)
{ ... }

Parameters

ChildList [in]

A handle to a framework child-list object.

IdentificationDescription [in, out]

A pointer to a WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER structure that identifies an identification description.

Return value

None

Remarks

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

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

Typically, the EvtChildListIdentificationDescriptionDuplicate callback function allocates memory by calling ExAllocatePool. The EvtChildListIdentificationDescriptionCleanup callback function must deallocate that memory by calling ExFreePool. This callback function must not attempt to deallocate the rest of the identification description. In other words, the callback function must not deallocate the address description structure that the IdentificationDescription 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 EvtChildListIdentificationDescriptionCleanup 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 EvtChildListIdentificationDescriptionCleanup callback function that is named MyChildListIdentificationDescriptionCleanup, use the EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_CLEANUP type as shown in this code example:


EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_CLEANUP  MyChildListIdentificationDescriptionCleanup;

Then, implement your callback function as follows:



_Use_decl_annotations_
VOID
 MyChildListIdentificationDescriptionCleanup (
 WDFCHILDLIST  ChildList,
    PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER  IdentificationDescription
    )
  {...}

The EVT_WDF_CHILD_LIST_IDENTIFICATION_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_IDENTIFICATION_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

Minimum KMDF version

1.0

Header

WdfChildlist.h (include Wdf.h)

IRQL

<= DISPATCH_LEVEL

See also

ExAllocatePool
ExFreePool
EvtChildListIdentificationDescriptionDuplicate
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER
WdfChildListCreate
WdfFdoInitSetDefaultChildListConfig

 

 

Send comments about this topic to Microsoft

Mostrar:
© 2014 Microsoft