EvtChildListCreateDevice function

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

NTSTATUS EvtChildListCreateDevice(
  _In_ WDFCHILDLIST                                 ChildList,
  _In_ PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription,
  _In_ PWDFDEVICE_INIT                              ChildInit
)
{ ... }

Parameters

ChildList [in]

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

IdentificationDescription [in]

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

ChildInit [in]

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.

Examples

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


EVT_WDF_CHILD_LIST_CREATE_DEVICE  MyChildListCreateDevice;

Then, implement your callback function as follows:


_Use_decl_annotations_
NTSTATUS
 MyChildListCreateDevice (
 WDFCHILDLIST  ChildList,
    PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER  IdentificationDescription,
    PWDFDEVICE_INIT  ChildInit
    )
  {...}

The EVT_WDF_CHILD_LIST_CREATE_DEVICE 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_CREATE_DEVICE 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 also

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER
WdfChildListAddOrUpdateChildDescriptionAsPresent
WdfChildListCreate
WdfChildListUpdateAllChildDescriptionsAsPresent
WDFDEVICE_INIT
WdfDeviceCreate
WdfFdoInitSetDefaultChildListConfig

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft