EVT_WDF_CHILD_LIST_SCAN_FOR_CHILDREN callback function

[Applies to KMDF only]

A driver's EvtChildListScanForChildren event callback function must report all of the child devices that are present.

Syntax


EVT_WDF_CHILD_LIST_SCAN_FOR_CHILDREN EvtChildListScanForChildren;

VOID EvtChildListScanForChildren(
  _In_ WDFCHILDLIST ChildList
)
{ ... }

Parameters

ChildList [in]

A handle to a framework child list object.

Return value

None

Remarks

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

If a driver provides an EvtChildListScanForChildren callback function, the framework calls it each time the parent device enters its working (D0) state. (For more information about when this callback function is called, see PnP and Power Management Scenarios.)

The driver must report all of its child devices by doing the following:

  1. Calling WdfChildListBeginScan, which marks all previously reported child devices as missing.

  2. Detecting child devices and calling WdfChildListAddOrUpdateChildDescriptionAsPresent for each detected device.

  3. Calling WdfChildListEndScan, which informs the PnP manager of the reported child devices.

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

The EvtChildListScanForChildren callback function is called at IRQL = PASSIVE_LEVEL. You should not make this callback function pageable.

Examples

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

To define an EvtChildListScanForChildren callback function that is named MyChildListScanForChildren, you must first provide a function declaration that SDV and other verification tools require, as follows:


EVT_WDF_CHILD_LIST_SCAN_FOR_CHILDREN  MyChildListScanForChildren;

Then, implement your callback function as follows:


_Use_decl_annotations_
VOID
 MyChildListScanForChildren (
 WDFCHILDLIST  ChildList
    )
  {...}

The EVT_WDF_CHILD_LIST_SCAN_FOR_CHILDREN 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_SCAN_FOR_CHILDREN 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

PASSIVE_LEVEL (see Remarks section)

See also

WdfChildListAddOrUpdateChildDescriptionAsPresent
WdfChildListBeginScan
WdfChildListCreate
WdfChildListEndScan
WdfFdoInitSetDefaultChildListConfig

 

 

Send comments about this topic to Microsoft

Show: