EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE Rückruffunktion (wdfchildlist.h)

Artikel
03/01/2024

[Gilt nur für KMDF]

Die EvtChildListIdentificationDescriptionDuplicate-Ereignisrückruffunktion eines Treibers dupliziert eine beschreibung der untergeordneten Identifizierung.

Syntax

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE EvtWdfChildListIdentificationDescriptionDuplicate;

NTSTATUS EvtWdfChildListIdentificationDescriptionDuplicate(
  [in]  WDFCHILDLIST ChildList,
  [in]  PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SourceIdentificationDescription,
  [out] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER DestinationIdentificationDescription
)
{...}

Parameter

[in] ChildList

Ein Handle für ein Frameworkobjekt mit untergeordneter Liste.

[in] SourceIdentificationDescription

Ein Zeiger auf eine WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER-Struktur , die den Quellspeicherort der untergeordneten Identifikationsbeschreibung identifiziert.

[out] DestinationIdentificationDescription

Ein Zeiger auf eine WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Struktur, die den Zielspeicherort der doppelten untergeordneten Identifikationsbeschreibung identifiziert.

Rückgabewert

Die Rückruffunktion EvtChildListIdentificationDescriptionDuplicate muss STATUS_SUCCESS oder einen anderen status Wert zurückgeben, für den NT_SUCCESS(status) true entspricht, wenn der Vorgang erfolgreich ist. Andernfalls muss diese Rückruffunktion einen status Wert zurückgeben, für den NT_SUCCESS(status) false entspricht.

Hinweise

Wenn ein Bustreiber eine dynamische Enumeration verwendet, kann er eine EvtChildListIdentificationDescriptionDuplicate-Rückruffunktion registrieren, indem er WdfFdoInitSetDefaultChildListConfig oder WdfChildListCreate aufruft.

Das Framework dupliziert vom Treiber bereitgestellte Identifizierungsbeschreibungen, sodass es interne Kopien der Beschreibungen haben kann.

Die Rückruffunktion EvtChildListIdentificationDescriptionDuplicate muss eine doppelte Kopie einer Identifikationsbeschreibung erstellen. Ein Treiber muss diese Rückruffunktion bereitstellen, wenn das Framework rtlCopyMemory nicht aufrufen kann, um die Identifikationsbeschreibung zu duplizieren. (Das Framework kann RtlCopyMemory nicht aufrufen, wenn die Beschreibung Zeiger auf zusätzlichen Arbeitsspeicher enthält.)

Wenn Ihr Treiber keine EvtChildListIdentificationDescriptionDuplicate-Rückruffunktion bereitstellt, dupliziert das Framework Identifikationsbeschreibungen durch Aufrufen von RtlCopyMemory.

In den folgenden Schritten wird ein typisches Szenario beschrieben:

Der Treiber bestimmt, dass ein untergeordnetes Gerät vorhanden ist.
Der Treiber erstellt eine Identifikationsbeschreibung, indem er eine vom Treiber definierte Struktur eingibt, die eine WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER-Struktur enthält, und möglicherweise durch dynamische Zuweisung von Zusätzlichem Arbeitsspeicher zum Speichern von Identifikationsinformationen mit einer gerätespezifischen Größe.
Der Treiber ruft WdfChildListAddOrUpdateChildDescriptionAsPresent auf, um ein untergeordnetes Gerät zu melden, und gibt einen Zeiger auf die Identifikationsbeschreibung an.
Das Framework ruft die Rückruffunktion EvtChildListIdentificationDescriptionDuplicate (sofern vorhanden) oder RtlCopyMemory auf, um die Identifikationsbeschreibung zu duplizieren, sodass eine interne Kopie der Beschreibung vorhanden ist.

Das Framework kann RtlCopyMemory verwenden, um eine Identifikationsbeschreibung zu duplizieren, wenn die Beschreibung aus einer einzelnen Struktur mit einer vordefinierten Größe besteht, die vom IdentificationDescriptionSize-Element 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 werden. In diesem Fall definieren Sie in der Regel eine Beschreibungsstruktur, sodass ein Member auf den dynamisch zugeordneten Arbeitsspeicher verweist, und Ihr Treiber muss eine EvtChildListIdentificationDescriptionDuplicate-Rückruffunktion bereitstellen. Die Rückruffunktion muss Folgendes ausführen:

Weisen Sie zusätzlichen Arbeitsspeicher zu, in der Regel durch Aufrufen von ExAllocatePool.
Speichern Sie die Adresse des zugeordneten Arbeitsspeichers in der vom Treiber definierten Adressbeschreibungsstruktur (d.a. der DestinationIdentificationDescription-Struktur der Rückruffunktion).
Kopieren Sie andere Strukturmember aus der SourceIdentificationDescription-Struktur der Rückruffunktion in die DestinationIdentificationDescription-Struktur der Rückruffunktion.

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

Das Framework ruft eine interne Objektsperre für untergeordnete Listen ab, bevor die Rückruffunktion EvtChildListIdentificationDescriptionDuplicate aufgerufen wird . Diese Rückruffunktion darf nur Vorgänge ausführen, die sich auf den Duplizierungsvorgang beziehen, z. B. das Aufrufen von Framework-Speicherobjektmethoden und den Zugriff auf Objektkontextbereich. Methoden, die auf andere Treiber zugreifen, dürfen nicht aufgerufen werden.

Wenn Ihr Treiber eine Rückruffunktion EvtChildListIdentificationDescriptionDuplicate bereitstellt, benötigt er möglicherweise auch die Rückruffunktionen EvtChildListIdentificationDescriptionCopy, EvtChildListIdentificationDescriptionCompare und EvtChildListIdentificationDescriptionCleanup .

Weitere Informationen zur dynamischen Enumeration finden Sie unter Auflisten der Geräte in einem Bus.