EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE Rückruffunktion (wdfchildlist.h)

Artikel
02/07/2025

[Gilt nur für KMDF]

Die EvtChildListIdentificationDescriptionCompare Ereignisrückruffunktion eines Treibers vergleicht eine untergeordnete Identifikationsbeschreibung mit einer anderen.

Syntax

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE EvtWdfChildListIdentificationDescriptionCompare;

BOOLEAN EvtWdfChildListIdentificationDescriptionCompare(
  [in] WDFCHILDLIST ChildList,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER FirstIdentificationDescription,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SecondIdentificationDescription
)
{...}

Parameter

[in] ChildList

Ein Handle für ein framework untergeordnetes Listenobjekt.

[in] FirstIdentificationDescription

Ein Zeiger auf eine WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Struktur, die die beschreibung einer untergeordneten Identifikation identifiziert.

[in] SecondIdentificationDescription

Ein Zeiger auf eine WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Struktur, die eine weitere Beschreibung der untergeordneten Identifizierung identifiziert.

Rückgabewert

Die EvtChildListIdentificationDescriptionCompare Rückruffunktion muss TRUE- zurückgeben, wenn die beiden untergeordneten Identifikationsbeschreibungen übereinstimmen. Andernfalls muss diese Funktion FALSE-zurückgeben.

Bemerkungen

Wenn ein Bustreiber dynamische Enumeration verwendet, kann er eine EvtChildListIdentificationDescriptionCompare Rückruffunktion registrieren, indem WdfFdoInitSetDefaultChildListConfig oder WdfChildListCreateaufgerufen wird. Der Treiber kann auch eine zweite Sonderfall-EvtChildListIdentificationDescriptionCompare Rückruffunktion registrieren, wenn sie WdfChildListRetrieveNextDeviceaufruft.

Das Framework vergleicht zwei Identifikationsbeschreibungen, wenn ermittelt werden muss, ob beide Beschreibungen dasselbe Gerät identifizieren.

Die EvtChildListIdentificationDescriptionCompare Rückruffunktion muss den Inhalt von zwei Identifikationsbeschreibungen vergleichen und TRUE- zurückgeben, wenn sie übereinstimmen. Ein Treiber muss diese Rückruffunktion bereitstellen, wenn das Framework nicht RtlCompareMemory- aufrufen kann, um die Identifikationsbeschreibungen zu vergleichen. (Das Framework kann RtlCompareMemory- nicht aufrufen, wenn die Beschreibungen Zeiger auf zusätzlichen Arbeitsspeicher enthalten.)

Wenn Ihr Treiber keine EvtChildListIdentificationDescriptionCompare Rückruffunktion bereitstellt, vergleicht das Framework Identifikationsbeschreibungen durch Aufrufen RtlCompareMemory.

Die folgenden Schritte beschreiben ein mögliches Szenario:

Der Treiber ruft WdfChildListRetrieveAddressDescription auf, um die Adressbeschreibung abzurufen, die der Kopie des Frameworks einer Identifikationsbeschreibung zugeordnet ist, die in einer untergeordneten Liste gespeichert ist.
Das Framework durchläuft die untergeordnete Liste. Um festzustellen, ob die Identifikationsbeschreibung eines untergeordneten Elements mit dem treiber übereinstimmt, der beim Aufruf WdfChildListRetrieveAddressDescriptionangegeben wurde, ruft das Framework entweder die EvtChildListIdentificationDescriptionCompare Rückruffunktion (sofern vorhanden) oder RtlCompareMemoryauf.
Wenn die beiden Identifikationsbeschreibungen übereinstimmen (und der Vergleich TRUEzurückgibt), durchläuft das Framework die Liste nicht mehr.
Das Framework kopiert die Adressbeschreibung in den Arbeitsspeicher, den der Treiber beim Aufrufen WdfChildListRetrieveAddressDescriptionangegeben hat.

Das Framework kann RtlCompareMemory verwenden, um Identifikationsbeschreibungen zu vergleichen, wenn jede Beschreibung aus einer einzelnen Struktur mit einer vordefinierten Größe besteht, die durch das IdentificationDescriptionSize Member der WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Struktur angegeben wird. Manchmal muss die Beschreibung jedoch auch zusätzliche Informationen enthalten, die im dynamisch zugeordneten Speicher gespeichert sind. In diesem Fall definieren Sie in der Regel eine Beschreibungsstruktur, sodass ein Element auf den dynamisch zugewiesenen Speicher verweist, und Ihr Treiber muss eine EvtChildListIdentificationDescriptionCompare Rückruffunktion bereitstellen.

Diese Rückruffunktion bestimmt, ob zwei Identifikationsbeschreibungen dasselbe Gerät darstellen. Die Rückruffunktion muss möglicherweise nicht alle Strukturmber vergleichen, um diese Bestimmung zu treffen. Angenommen, eine Identifikationsbeschreibung enthält eine Seriennummer und eine Reihe von Hardwarebezeichnern wie folgt:

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

In diesem Fall muss die EvtChildListIdentificationDescriptionCompare Rückruffunktion wahrscheinlich nur die DeviceSerialNumber Member vergleichen, um festzustellen, ob zwei Beschreibungen dasselbe Gerät darstellen.

Wenn Ihr Treiber WdfChildListRetrieveNextDevice aufruft, um eine Geräteliste zu durchlaufen, können Sie eine zusätzliche EvtChildListIdentificationDescriptionCompare Rückruffunktion bereitstellen, die das Framework bei der Suche nach der nächsten abzurufenden Beschreibung verwendet. Das Framework sucht nach untergeordneten Geräten, die den vom Treiber bereitgestellten WDF_RETRIEVE_CHILD_FLAGS-typed flags entsprechen. Wenn ein Treiber eine spezielle EvtChildListIdentificationDescriptionCompare Rückruffunktion bereitstellt, verwendet das Framework die Rückruffunktion, um die Suche zu verfeinern. Wenn der Treiber keine spezielle EvtChildListIdentificationDescriptionCompare Rückruffunktion liefert, das Framework nicht Aufruf RtlCompareMemory-- es gibt einfach jedes untergeordnete Gerät zurück, das den angegebenen Flags entspricht.

Die einzige Framework-Objektmethode für untergeordnete Listen, dass ein Treiber EvtChildListIdentificationDescriptionCompare Rückruffunktion aufrufen kann, ist WdfChildListGetDevice.

Das Framework erwirbt eine interne Objektsperre für untergeordnete Listen, bevor die EvtChildListIdentificationDescriptionCompareEvtChildListIdentificationDescriptionCompare Rückruffunktion aufgerufen wird. Die Rückruffunktion darf nur Vorgänge ausführen, die mit dem Vergleichsvorgang zusammenhängen, z. B. das Aufrufen von Framework-Speicherobjektmethoden und den Zugriff auf den Objektkontextbereich. Es darf keine Methoden aufrufen, die auf andere Treiber zugreifen.

Weitere Informationen zur dynamischen Aufzählung finden Sie unter Aufzählen der Geräte auf einem Bus-.