EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE Rückruffunktion (wdfchildlist.h)

Artikel
08/08/2023

[Gilt nur für KMDF]

Die EvtChildListIdentificationDescriptionCompare-Ereignisrückruffunktion eines Treibers vergleicht eine untergeordnete Identifizierungsbeschreibung 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-Objekt mit untergeordneter Liste.

[in] FirstIdentificationDescription

Ein Zeiger auf eine WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Struktur, die die eine untergeordnete Identifikationsbeschreibung identifiziert.

[in] SecondIdentificationDescription

Ein Zeiger auf eine WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Struktur, die eine andere beschreibung der untergeordneten Identifizierung identifiziert.

Rückgabewert

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

Hinweise

Wenn ein Bustreiber eine dynamische Enumeration verwendet, kann er eine EvtChildListIdentificationDescriptionCompare-Rückruffunktion registrieren, indem er WdfFdoInitSetDefaultChildListConfig oder WdfChildListCreate aufruft. Der Treiber kann auch eine zweite EvtChildListIdentificationDescriptionCompare-Rückruffunktion registrieren, wenn er WdfChildListRetrieveNextDevice aufruft.

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

Die Rückruffunktion EvtChildListIdentificationDescriptionCompare muss den Inhalt von zwei Identifizierungsbeschreibungen vergleichen und TRUE zurückgeben, wenn diese übereinstimmen. Ein Treiber muss diese Rückruffunktion bereitstellen, wenn das Framework rtlCompareMemory nicht aufrufen kann, um die Identifizierungsbeschreibungen 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 Identifizierungsbeschreibungen durch Aufrufen von RtlCompareMemory.

In den folgenden Schritten wird ein mögliches Szenario beschrieben:

Der Treiber ruft WdfChildListRetrieveAddressDescription auf, um die Adressbeschreibung abzurufen, die der Kopie einer Identifikationsbeschreibung des Frameworks zugeordnet ist, die in einer untergeordneten Liste gespeichert ist.
Das Framework durchläuft die untergeordnete Liste. Um zu ermitteln, ob die Identifikationsbeschreibung eines untergeordneten Elements mit der vom Treiber beim Aufruf von WdfChildListRetrieveAddressDescription angegebenen übereinstimmt, ruft das Framework entweder die Rückruffunktion EvtChildListIdentificationDescriptionCompare ( sofern vorhanden) oder RtlCompareMemory auf.
Wenn die beiden Identifizierungsbeschreibungen übereinstimmen (und der Vergleich TRUE zurückgibt), beendet das Framework die Durchquerung der Liste.
Das Framework kopiert die Adressbeschreibung in den Arbeitsspeicher, die der Treiber beim Aufrufen von WdfChildListRetrieveAddressDescription bereitgestellt hat.

Das Framework kann RtlCompareMemory verwenden, um Identifizierungsbeschreibungen zu vergleichen, wenn jede Beschreibung aus einer einzelnen Struktur mit einer vordefinierten Größe besteht, die vom 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 Arbeitsspeicher gespeichert sind. In diesem Fall definieren Sie in der Regel eine Beschreibungsstruktur, sodass ein Member auf den dynamisch zugeordneten Speicher verweist und Ihr Treiber eine EvtChildListIdentificationDescriptionCompare-Rückruffunktion bereitstellen muss.

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

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 Rückruffunktion EvtChildListIdentificationDescriptionCompare wahrscheinlich nur die DeviceSerialNumber-Member vergleichen, um zu ermitteln, 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 verwendet, wenn nach der nächsten abzurufenden Beschreibung gesucht wird. Das Framework sucht nach untergeordneten Geräten, die WDF_RETRIEVE_CHILD_FLAGS vom Treiber bereitgestellten 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 bereitstellt, ruft das Framework rtlCompareMemorynicht auf, es gibt einfach jedes untergeordnete Gerät zurück, das den angegebenen Flags entspricht.

Die einzige Framework-Child-List-Objektmethode , die von der EvtChildListIdentificationDescriptionCompare-Rückruffunktion eines Treibers aufgerufen werden kann, ist WdfChildListGetDevice.

Das Framework ruft vor dem Aufrufen der Rückruffunktion EvtChildListIdentificationDescriptionCompareEvtChildListIdentificationDescriptionCompare eine interne Objektsperre für untergeordnete Listen ab. Die Rückruffunktion darf nur Vorgänge ausführen, die sich auf den Vergleichsvorgang beziehen, 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 Enumeration finden Sie unter Auflisten der Geräte in einem Bus.