EvtChildListDeviceReenumerated function

[Applies to KMDF only]

A driver's EvtChildListDeviceReenumerated event callback function enables the driver to approve or cancel a reenumeration of a specified device.

Syntax


EVT_WDF_CHILD_LIST_DEVICE_REENUMERATED EvtChildListDeviceReenumerated;

BOOLEAN EvtChildListDeviceReenumerated(
  _In_   WDFCHILDLIST ChildList,
  _In_   WDFDEVICE OldDevice,
  _In_   PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER OldAddressDescription,
  _Out_  PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER NewAddressDescription
)
{ ... }

Parameters

ChildList [in]

A handle to a framework child list object.

OldDevice [in]

A handle to a framework device object.

OldAddressDescription [in]

A pointer to a WDF_CHILD_ADDRESS_DESCRIPTION_HEADER structure that identifies a child address description. This structure contains address information that was relevant before the device was reenumerated.

NewAddressDescription [out]

A pointer to a WDF_CHILD_ADDRESS_DESCRIPTION_HEADER structure that identifies a child address description. The callback function fills in this structure with new address information about the device.

Return value

The EvtChildListDeviceReenumerated callback function returns TRUE to approve the reenumeration or FALSE to cancel it.

Remarks

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

Framework-based bus drivers can receive a request from a function driver to reenumerate a particular child device. For more information about these requests, see Handling Enumeration Requests.

The bus driver's EvtChildListDeviceReenumerated callback function enables the driver to approve or cancel the reenumeration. The OldDevice parameter identifies the device, and the ChildList parameter identifies the child list that the device is a member of. If the callback function returns TRUE to approve the reenumeration, or if the callback function does not exist, the framework does the following:

  1. Removes the device's framework device object (which is identified by OldDevice) but retains the device's identification description.

  2. Calls the driver's EvtChildListCreateDevice callback function, passing the saved identification description, so that the callback function can call WdfDeviceCreate to create a new framework device object.

The EvtChildListDeviceReenumerated callback function receives pointers to two address descriptions. One points to the address description that is associated with the old device object. The other points to an address description that the callback function must fill in with information that describes the device's current location.

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

Examples

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


EVT_WDF_CHILD_LIST_DEVICE_REENUMERATED  MyChildListDeviceReenumerated;

Then, implement your callback function as follows:


_Use_decl_annotations_
BOOLEAN
 MyChildListDeviceReenumerated (
 WDFCHILDLIST  ChildList,
 WDFDEVICE  OldDevice,
    PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER  OldAddressDescription,
    PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER  NewAddressDescription
    )
  {...}

The EVT_WDF_CHILD_LIST_DEVICE_REENUMERATED 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_DEVICE_REENUMERATED 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

EvtChildListCreateDevice
WDF_CHILD_ADDRESS_DESCRIPTION_HEADER
WdfChildListCreate
WdfDeviceCreate
WdfFdoInitSetDefaultChildListConfig

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft