EvtChildListAddressDescriptionCopy function

[Applies to KMDF only]

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

Syntax


EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY EvtChildListAddressDescriptionCopy;

VOID EvtChildListAddressDescriptionCopy(
  _In_   WDFCHILDLIST ChildList,
  _In_   PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER SourceAddressDescription,
  _Out_  PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER DestinationAddressDescription
)
{ ... }

Parameters

ChildList [in]

A handle to a framework child-list object.

SourceAddressDescription [in]

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

DestinationAddressDescription [out]

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

Return value

None

Remarks

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

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

The EvtChildListAddressDescriptionCopy callback function must copy the contents of a source description to a destination description. A driver must supply this callback function if its child devices require an address description, and if the framework cannot call RtlCopyMemory to copy 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 EvtChildListAddressDescriptionCopy callback function, the framework copies address descriptions by calling RtlCopyMemory.

The following steps describe a typical scenario:

  1. The driver determines that a child device exists.

  2. 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.

  3. The driver calls WdfChildListAddOrUpdateChildDescriptionAsPresent to report a child device, supplying a pointer to the address description.

  4. The framework determines that the driver had previously reported the device, so the framework can update the device's old address description with new information.

  5. The framework calls the EvtChildListAddressDescriptionCopy callback function (if it exists) or RtlCopyMemory to copy the new address description information into the existing address description.

The framework can use RtlCopyMemory to copy 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 EvtChildListAddressDescriptionCopy callback function. The callback function must do the following:

  1. In the callback function's SourceAddressDescription and DestinationAddressDescription structures, find the pointers to dynamically allocated memory.

  2. Copy the dynamically allocated memory from the source to the destination, using the pointers.

  3. 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 EvtChildListAddressDescriptionCopy callback function can call is WdfChildListGetDevice.

The framework acquires an internal child-list object lock before calling the EvtChildListAddressDescriptionCopy callback function. The callback function must only perform operations that are related to the described 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 EvtChildListAddressDescriptionCopy callback function, it might also need EvtChildListAddressDescriptionDuplicate and EvtChildListAddressDescriptionCleanup callback functions.

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

Examples

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


EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY MyChildListAddressDescriptionCopy;

Then, implement your callback function as follows:


_Use_decl_annotations_
VOID
 MyChildListAddressDescriptionCopy (
 WDFCHILDLIST  ChildList,
    PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER  SourceAddressDescription,
    PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER  DestinationAddressDescription
    )
  {...}

The EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION 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_ADDRESS_DESCRIPTION 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

Minimum KMDF version

1.0

Header

WdfChildlist.h (include Wdf.h)

IRQL

<= DISPATCH_LEVEL

See also

EvtChildListAddressDescriptionCleanup
EvtChildListAddressDescriptionDuplicate
RtlCopyMemory
WDF_CHILD_ADDRESS_DESCRIPTION_HEADER
WdfChildListAddOrUpdateChildDescriptionAsPresent
WdfChildListCreate
WdfChildListGetDevice
WdfFdoInitSetDefaultChildListConfig

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft