EVT_WDF_CHILD_LIST_DEVICE_REENUMERATED callback function (wdfchildlist.h)

Article
02/22/2024

[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 EvtWdfChildListDeviceReenumerated;

BOOLEAN EvtWdfChildListDeviceReenumerated(
  [in]  WDFCHILDLIST ChildList,
  [in]  WDFDEVICE OldDevice,
  [in]  PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER OldAddressDescription,
  [out] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER NewAddressDescription
)
{...}

Parameters

[in] ChildList

A handle to a framework child list object.

[in] OldDevice

A handle to a framework device object.

[in] OldAddressDescription

Optional pointer to a WDF_CHILD_ADDRESS_DESCRIPTION_HEADER structure that identifies a child address description, or NULL. If provided, this structure contains address information that was relevant before the device was reenumerated.

[out] NewAddressDescription

Optional pointer to a WDF_CHILD_ADDRESS_DESCRIPTION_HEADER structure that identifies a child address description, or NULL. If provided, 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:

Removes the device's framework device object (which is identified by OldDevice) but retains the device's identification description.
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.

If the bus driver uses address descriptions, 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.

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Header	wdfchildlist.h (include Wdf.h)
IRQL	<= DISPATCH_LEVEL