EVT_WDF_CHILD_LIST_CREATE_DEVICE callback function (wdfchildlist.h)

[Applies to KMDF only]

A bus driver'sEvtChildListCreateDevice event callback function creates a framework device object for a new device that has been dynamically enumerated.

Syntax

EVT_WDF_CHILD_LIST_CREATE_DEVICE EvtWdfChildListCreateDevice;

NTSTATUS EvtWdfChildListCreateDevice(
  [in] WDFCHILDLIST ChildList,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription,
  [in] PWDFDEVICE_INIT ChildInit
)
{...}

Parameters

[in] ChildList

A handle to the framework child-list object that the driver specified when it called WdfChildListAddOrUpdateChildDescriptionAsPresent.

[in] IdentificationDescription

A pointer to a copy of the WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER structure that the driver specified when it called WdfChildListAddOrUpdateChildDescriptionAsPresent.

[in] ChildInit

A pointer to a WDFDEVICE_INIT structure.

Return value

The EvtChildListCreateDevice callback function must return STATUS_SUCCESS, or another status value for which NT_SUCCESS(status) equals TRUE, if the operation succeeds. Otherwise, this function must return a status value for which NT_SUCCESS(status) equals FALSE.

If the operation failed but you think your driver should try again later, and if the driver's EvtChildListCreateDevice callback function has not called WdfDeviceCreate, the driver can return STATUS_RETRY. As a result, the framework calls the EvtChildListCreateDevice callback function again later. If your driver returns STATUS_RETRY more than a few times, the framework will stop calling the callback function for the failing device.

Remarks

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

After a driver calls WdfChildListAddOrUpdateChildDescriptionAsPresent or WdfChildListUpdateAllChildDescriptionsAsPresent, the framework calls the driver's EvtChildListCreateDevice callback function. The callback function must call WdfDeviceCreate to create a framework device object (a PDO).

Before calling WdfDeviceCreate, the driver must call framework-supplied functions that initialize the WDFDEVICE_INIT structure. For more information about these functions, see WDFDEVICE_INIT.

For more information about calling WdfDeviceCreate, see Creating a Framework Device Object.

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

Requirements

See also

WDFDEVICE_INIT

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER

WdfChildListAddOrUpdateChildDescriptionAsPresent

WdfChildListCreate

WdfChildListUpdateAllChildDescriptionsAsPresent

WdfDeviceCreate

WdfFdoInitSetDefaultChildListConfig