EvtChildListIdentificationDescriptionCompare function

[Applies to KMDF only]

A driver's EvtChildListIdentificationDescriptionCompare event callback function compares one child identification description with another.

Syntax


EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE EvtChildListIdentificationDescriptionCompare;

BOOLEAN EvtChildListIdentificationDescriptionCompare(
  _In_  WDFCHILDLIST ChildList,
  _In_  PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER FirstIdentificationDescription,
  _In_  PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SecondIdentificationDescription
)
{ ... }

Parameters

ChildList [in]

A handle to a framework child-list object.

FirstIdentificationDescription [in]

A pointer to a WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER structure that identifies the one child identification description.

SecondIdentificationDescription [in]

A pointer to a WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER structure that identifies another child identification description.

Return value

The EvtChildListIdentificationDescriptionCompare callback function must return TRUE if the two child identification descriptions match. Otherwise, this function must return FALSE.

Remarks

If a bus driver is using dynamic enumeration, it can register an EvtChildListIdentificationDescriptionCompare callback function by calling WdfFdoInitSetDefaultChildListConfig or WdfChildListCreate. The driver can also register a second, special-case EvtChildListIdentificationDescriptionCompare callback function when it calls WdfChildListRetrieveNextDevice.

The framework compares two identification descriptions when it must determine if both descriptions identify the same device.

The EvtChildListIdentificationDescriptionCompare callback function must compare the contents of two identification descriptions and return TRUE if they match. A driver must supply this callback function if the framework cannot call RtlCompareMemory to compare the identification descriptions. (The framework cannot call RtlCompareMemory if the descriptions contain pointers to additional memory.)

If your driver does not provide an EvtChildListIdentificationDescriptionCompare callback function, the framework compares identification descriptions by calling RtlCompareMemory.

The following steps describe a possible scenario:

  1. The driver calls WdfChildListRetrieveAddressDescription to obtain the address description that is associated with the framework's copy of an identification description, which is stored in a child list.

  2. The framework traverses the child list. To determine if a child's identification description matches the one that the driver specified when it called WdfChildListRetrieveAddressDescription, the framework calls either the EvtChildListIdentificationDescriptionCompare callback function (if it exists) or RtlCompareMemory.

  3. If the two identification descriptions match (and the comparison returns TRUE), the framework stops traversing the list.

  4. The framework copies the address description into memory that the driver supplied when it called WdfChildListRetrieveAddressDescription.

The framework can use RtlCompareMemory to compare identification descriptions, if each 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 EvtChildListIdentificationDescriptionCompare callback function.

This callback function determines if two identification descriptions represent the same device. The callback function might not have to compare all of the structure members to make that determination. For example, suppose that an identification description contains a serial number and a set of hardware identifiers, as follows:


typedef struct _PDO_IDENTIFICATION_DESCRIPTION {
  WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Header;
  ULONG DeviceSerialNumber;
  ULONG CchHardwareIds;
  PWCHAR HardwareIds;
} PDO_IDENTIFICATION_DESCRIPTION, *PPDO_IDENTIFICATION_DESCRIPTION;

In this case, the EvtChildListIdentificationDescriptionCompare callback function probably has to compare only the DeviceSerialNumber members to determine if two descriptions represent the same device.

If your driver calls WdfChildListRetrieveNextDevice to traverse a device list, you can provide an additional EvtChildListIdentificationDescriptionCompare callback function that the framework uses when looking for the next description to retrieve. The framework looks for child devices that match driver-supplied WDF_RETRIEVE_CHILD_FLAGS-typed flags. If a driver provides a special EvtChildListIdentificationDescriptionCompare callback function, the framework uses the callback function to refine the search. If the driver does not supply a special EvtChildListIdentificationDescriptionCompare callback function, the framework does not call RtlCompareMemory--it simply returns each child device that matches the specified flags.

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

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

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

Examples

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


EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE  MyChildListIdentificationDescriptionCompare;

Then, implement your callback function as follows:



_Use_decl_annotations_
BOOLEAN
 MyChildListIdentificationDescriptionCompare (
 WDFCHILDLIST  ChildList,
    PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER  FirstIdentificationDescription,
    PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER  SecondIdentificationDescription
    )
  {...}

The EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE 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_COMPARE 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

RtlCompareMemory
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER
WDF_RETRIEVE_CHILD_FLAGS
WdfChildListCreate
WdfChildListGetDevice
WdfChildListRetrieveAddressDescription
WdfChildListRetrieveNextDevice
WdfFdoInitSetDefaultChildListConfig

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft