EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COPY callback function (wdfchildlist.h)

Article
10/21/2021

[Applies to KMDF only]

A driver's EvtChildListIdentificationDescriptionCopy event callback function copies a child identification description from one specified location to another.

Syntax

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COPY EvtWdfChildListIdentificationDescriptionCopy;

void EvtWdfChildListIdentificationDescriptionCopy(
  [in]  WDFCHILDLIST ChildList,
  [in]  PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SourceIdentificationDescription,
  [out] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER DestinationIdentificationDescription
)
{...}

Parameters

[in] ChildList

A handle to a framework child-list object.

[in] SourceIdentificationDescription

A pointer to a WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER structure that identifies the source location of the child identification description.

[out] DestinationIdentificationDescription

A pointer to a WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER structure that identifies the destination location of the child identification description.

Return value

None

Remarks

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

The framework copies information from one driver-supplied identification description to another when it needs to update an existing description with new information, or when it needs to pass the contents of an identification description to the driver.

The EvtChildListIdentificationDescriptionCopy callback function must copy the contents of a source description to a destination description. A driver must supply this callback function if the framework cannot call RtlCopyMemory to copy the identification description. (The framework cannot call RtlCopyMemory if the description contains pointers to additional memory.)

If your driver does not provide an EvtChildListIdentificationDescriptionCopy callback function, the framework copies identification descriptions by calling RtlCopyMemory.

The following steps describe a possible scenario:

The driver that is traversing a child list calls WdfChildListRetrieveNextDevice. The driver supplies a WDF_CHILD_RETRIEVE_INFO structure so that it can receive the child device's identification description.
The framework calls the EvtChildListIdentificationDescriptionCopy callback function (if it exists) or RtlCopyMemory to copy the device's identification description. The source of the copy operation is the framework's internal copy of the description. The destination is memory that the driver allocated and identified in its WDF_CHILD_RETRIEVE_INFO structure.

The framework can use RtlCopyMemory to copy an identification description, if the description consists of a single structure with a predetermined size that is specified by the IdentificationDescriptionSize member of the WDF_CHILD_IDENTIFICATION_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 EvtChildListIdentificationDescriptionCopy callback function. The callback function must do the following:

In the callback function's SourceIdentificationDescription and DestinationIdentificationDescription structures, find the pointers to dynamically allocated memory.
Copy the dynamically allocated memory from the source to the destination, using the pointers.
Copy other structure members from the callback function's SourceIdentificationDescription structure to the callback function's DestinationIdentificationDescription structure.

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

The framework acquires an internal child-list object lock before calling the EvtChildListIdentificationDescriptionCopy callback function. The callback function must only perform operations that are related to the copy 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 EvtChildListIdentificationDescriptionCopy callback function, it might also need EvtChildListIdentificationDescriptionDuplicate, EvtChildListIdentificationDescriptionCompare, and EvtChildListIdentificationDescriptionCleanup 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