EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE callback function (wdfchildlist.h)

Article
10/21/2021

[Applies to KMDF only]

A driver's EvtChildListAddressDescriptionDuplicate event callback function duplicates a child address description.

Syntax

EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE EvtWdfChildListAddressDescriptionDuplicate;

NTSTATUS EvtWdfChildListAddressDescriptionDuplicate(
  [in]  WDFCHILDLIST ChildList,
  [in]  PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER SourceAddressDescription,
  [out] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER DestinationAddressDescription
)
{...}

Parameters

[in] ChildList

A handle to a framework child-list object.

[in] SourceAddressDescription

A pointer to a WDF_CHILD_ADDRESS_DESCRIPTION_HEADER structure that identifies the source location of the child address description.

[out] DestinationAddressDescription

A pointer to a WDF_CHILD_ADDRESS_DESCRIPTION_HEADER structure that identifies the destination location of the child address description.

Return value

The EvtChildListAddressDescriptionDuplicate 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.

Remarks

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

The framework duplicates driver-supplied address descriptions so that it can have internal copies of the descriptions.

The EvtChildListAddressDescriptionDuplicate callback function must create a duplicate copy of an address description. A driver must supply this callback function if its child devices require an address description, and if the framework cannot call RtlCopyMemory to duplicate the address description. (The framework cannot call RtlCopyMemory if the description contains pointers to additional memory.)

If your driver provides address descriptions but does not provide a EvtChildListAddressDescriptionDuplicate callback function, the framework duplicates address descriptions by calling RtlCopyMemory.

The following steps describe a typical scenario:

The driver determines that a child device exists.
The driver creates an address description by filling in a driver-defined structure that contains a WDF_CHILD_ADDRESS_DESCRIPTION_HEADER structure and possibly by dynamically allocating additional memory to store address information that has a device-specific size.
The driver calls WdfChildListAddOrUpdateChildDescriptionAsPresent to report a child device, supplying a pointer to the address description.
The framework calls the EvtChildListAddressDescriptionDuplicate callback function (if it exists) or RtlCopyMemory to duplicate the address description so that it can have an internal copy of the description.

The framework can use RtlCopyMemory to duplicate an address description, if the description consists of a single structure with a predetermined size that is specified by the AddressDescriptionSize member of the WDF_CHILD_ADDRESS_DESCRIPTION_HEADER structure. However, sometimes the description must also contain additional information that is stored in dynamically allocated memory. In this case, you will typically define a description structure so that a member points to the dynamically allocated memory, and your driver must provide an EvtChildListAddressDescriptionDuplicate callback function. The callback function must do the following:

Allocate additional memory, typically by calling ExAllocatePool.
Store the allocated memory's address in the driver-defined address description structure (that is, the callback function's DestinationAddressDescription structure).
Copy other structure members from the callback function's SourceAddressDescription structure to the callback function's DestinationAddressDescription structure.

The only framework child-list object method that a driver's EvtChildListAddressDescriptionDuplicate callback function can call is WdfChildListGetDevice.

The framework acquires an internal child-list object lock before calling the EvtChildListAddressDescriptionDuplicate callback function. The callback function must only perform operations that are related to the described duplication operation, such as calling framework memory object methods and accessing object context space. It must not call methods that access other drivers.

If your driver supplies an EvtChildListAddressDescriptionDuplicate callback function, it might also need EvtChildListAddressDescriptionCopy and EvtChildListAddressDescriptionCleanup callback functions.

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