EvtChildListIdentificationDescriptionDuplicate function

[Applies to KMDF only]

A driver's EvtChildListIdentificationDescriptionDuplicate event callback function duplicates a child identification description.

Syntax


EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE EvtChildListIdentificationDescriptionDuplicate;

NTSTATUS EvtChildListIdentificationDescriptionDuplicate(
  _In_   WDFCHILDLIST ChildList,
  _In_   PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SourceIdentificationDescription,
  _Out_  PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER DestinationIdentificationDescription
)
{ ... }

Parameters

ChildList [in]

A handle to a framework child-list object.

SourceIdentificationDescription [in]

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

DestinationIdentificationDescription [out]

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

Return value

The EvtChildListIdentificationDescriptionDuplicate callback function must return STATUS_SUCCESS, or another status value for which NT_SUCCESS(status) equals TRUE, if the operation succeeds. Otherwise, this callback 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 EvtChildListIdentificationDescriptionDuplicate callback function by calling WdfFdoInitSetDefaultChildListConfig or WdfChildListCreate.

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

The EvtChildListIdentificationDescriptionDuplicate callback function must create a duplicate copy of an identification description. A driver must supply this callback function if the framework cannot call RtlCopyMemory to duplicate the identification description. (The framework cannot call RtlCopyMemory if the description contains pointers to additional memory.)

If your driver does not provide an EvtChildListIdentificationDescriptionDuplicate callback function, the framework duplicates identification 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 identification description by filling in a driver-defined structure that contains a WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER structure and possibly by dynamically allocating addition memory to store identification information that has a device-specific size.

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

  4. The framework calls the EvtChildListIdentificationDescriptionDuplicate callback function (if it exists) or RtlCopyMemory to duplicate the identification description so that it can have an internal copy of the description.

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

  1. Allocate additional memory, typically by calling ExAllocatePool.

  2. Store the allocated memory's address in the driver-defined address description structure (that is, the callback function's DestinationIdentificationDescription structure).

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

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

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

Examples

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

To define an EvtChildListIdentificationDescriptionDuplicate callback function that is named MyChildListIdentificationDescriptionDuplicate, you must first provide a function declaration that SDV and other verification tools require, as follows:


EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE  MyChildListIdentificationDescriptionDuplicate;

Then, implement your callback function as follows:


_Use_decl_annotations_
NTSTATUS
 MyChildListIdentificationDescriptionDuplicate (
 WDFCHILDLIST  ChildList,
    PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER  SourceIdentificationDescription,
    PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER  DestinationIdentificationDescription
    )
  {...}

The EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE 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_IDENTIFICATION_DESCRIPTION_DUPLICATE 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

EvtChildListIdentificationDescriptionCleanup
EvtChildListIdentificationDescriptionCompare
EvtChildListIdentificationDescriptionCopy
ExAllocatePool
RtlCopyMemory
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER
WdfChildListAddOrUpdateChildDescriptionAsPresent
WdfChildListCreate
WdfChildListGetDevice
WdfFdoInitSetDefaultChildListConfig

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft