EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE Rückruffunktion (wdfchildlist.h)

Artikel
02/07/2025

[Gilt nur für KMDF]

Die EvtChildListIdentificationDescriptionDuplicate Ereignisrückruffunktion dupliziert eine Beschreibung der untergeordneten Identifikation.

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 framework untergeordnetes Listenobjekt.

[in] SourceIdentificationDescription

Ein Zeiger auf eine WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Struktur, die den Quellspeicherort der Beschreibung der untergeordneten Identifikation identifiziert.

[out] DestinationIdentificationDescription

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

Rückgabewert

Die EvtChildListIdentificationDescriptionDuplicate Rückruffunktion muss STATUS_SUCCESS oder einen anderen Statuswert zurückgeben, für den NT_SUCCESS(Status) TRUEentspricht, wenn der Vorgang erfolgreich ist. Andernfalls muss diese Rückruffunktion einen Statuswert zurückgeben, für den NT_SUCCESS(Status) FALSE-entspricht.

Bemerkungen

Wenn ein Bustreiber dynamische Enumerationverwendet, kann er eine EvtChildListIdentificationDescriptionDuplicate Rückruffunktion registrieren, indem WdfFdoInitSetDefaultChildListConfig oder WdfChildListCreateaufgerufen wird.

Das Framework dupliziert vom Treiber bereitgestellte Identifikationsbeschreibungen, sodass es interne Kopien der Beschreibungen enthalten kann.

Die EvtChildListIdentificationDescriptionDuplicate Rückruffunktion muss eine duplizierte Kopie einer Identifikationsbeschreibung erstellen. Ein Treiber muss diese Rückruffunktion bereitstellen, wenn das Framework nicht RtlCopyMemory- 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, indem RtlCopyMemoryaufgerufen wird.

Die folgenden Schritte beschreiben ein typisches Szenario:

Der Treiber bestimmt, dass ein untergeordnetes Gerät vorhanden ist.
Der Treiber erstellt eine Identifikationsbeschreibung, indem eine treiberdefinierte Struktur ausgefüllt wird, die eine WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Struktur enthält, und möglicherweise durch dynamische Zuordnung des Zusätzlichen Speichers zum Speichern von Identifikationsinformationen mit einer gerätespezifischen Größe.
Der Treiber ruft WdfChildListAddOrUpdateChildDescriptionAsPresent auf, um ein untergeordnetes Gerät zu melden, wobei ein Zeiger auf die Identifikationsbeschreibung bereitgestellt wird.
Das Framework ruft die EvtChildListIdentificationDescriptionDuplicate Rückruffunktion (sofern vorhanden) oder RtlCopyMemory auf, um die Identifikationsbeschreibung zu duplizieren, sodass sie eine interne Kopie der Beschreibung aufweisen kann.

Das Framework kann RtlCopyMemory verwenden, um eine Identifikationsbeschreibung zu duplizieren, wenn die 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 EvtChildListIdentificationDescriptionDuplicate Rückruffunktion bereitstellen. Die Rückruffunktion muss folgende Aktionen ausführen:

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

Die einzige Framework-Child-List-Objektmethode, die ein Treiber EvtChildListIdentificationDescriptionDuplicate Rückruffunktion aufrufen kann, ist WdfChildListGetDevice.

Das Framework ruft vor dem Aufrufen der EvtChildListIdentificationDescriptionDuplicate Rückruffunktion eine interne Objektsperre für untergeordnete Listen ab. 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 den Objektkontextbereich. Es darf keine Methoden aufrufen, die auf andere Treiber zugreifen.

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

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