EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE Rückruffunktion (wdfchildlist.h)

Artikel
02/07/2025

[Gilt nur für KMDF]

Die EvtChildListAddressDescriptionDuplicate Ereignisrückruffunktion dupliziert eine untergeordnete Adressbeschreibung.

Syntax

EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE EvtWdfChildListAddressDescriptionDuplicate;

NTSTATUS EvtWdfChildListAddressDescriptionDuplicate(
  [in]  WDFCHILDLIST ChildList,
  [in]  PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER SourceAddressDescription,
  [out] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER DestinationAddressDescription
)
{...}

Parameter

[in] ChildList

Ein Handle für ein framework untergeordnetes Listenobjekt.

[in] SourceAddressDescription

Ein Zeiger auf eine WDF_CHILD_ADDRESS_DESCRIPTION_HEADER Struktur, die den Quellspeicherort der untergeordneten Adressbeschreibung identifiziert.

[out] DestinationAddressDescription

Ein Zeiger auf eine WDF_CHILD_ADDRESS_DESCRIPTION_HEADER Struktur, die den Zielspeicherort der untergeordneten Adressbeschreibung identifiziert.

Rückgabewert

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

Bemerkungen

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

Das Framework dupliziert die vom Treiber bereitgestellten Adressbeschreibungen, sodass es interne Kopien der Beschreibungen enthalten kann.

Die EvtChildListAddressDescriptionDuplicate Rückruffunktion muss eine doppelte Kopie einer Adressbeschreibung erstellen. Ein Treiber muss diese Rückruffunktion angeben, wenn seine untergeordneten Geräte eine Adressbeschreibung erfordern und wenn das Framework RtlCopyMemory nicht aufrufen kann, um die Adressbeschreibung zu duplizieren. (Das Framework kann RtlCopyMemory- nicht aufrufen, wenn die Beschreibung Zeiger auf zusätzlichen Arbeitsspeicher enthält.)

Wenn Ihr Treiber Adressbeschreibungen bereitstellt, aber keine EvtChildListAddressDescriptionDuplicate Rückruffunktion bereitstellt, dupliziert das Framework Adressbeschreibungen durch Aufrufen von RtlCopyMemory.

Die folgenden Schritte beschreiben ein typisches Szenario:

Der Treiber bestimmt, dass ein untergeordnetes Gerät vorhanden ist.
Der Treiber erstellt eine Adressbeschreibung, indem eine treiberdefinierte Struktur ausgefüllt wird, die eine WDF_CHILD_ADDRESS_DESCRIPTION_HEADER Struktur enthält, und möglicherweise durch dynamisches Zuordnen von zusätzlichem Arbeitsspeicher zum Speichern von Adressinformationen mit einer gerätespezifischen Größe.
Der Treiber ruft WdfChildListAddOrUpdateChildDescriptionAsPresent auf, um ein untergeordnetes Gerät zu melden, wobei ein Zeiger auf die Adressbeschreibung bereitgestellt wird.
Das Framework ruft die EvtChildListAddressDescriptionDuplicate Rückruffunktion (sofern vorhanden) oder RtlCopyMemory- auf, um die Adressbeschreibung zu duplizieren, sodass sie eine interne Kopie der Beschreibung aufweisen kann.

Das Framework kann RtlCopyMemory verwenden, um eine Adressbeschreibung zu duplizieren, wenn die Beschreibung aus einer einzelnen Struktur mit einer vordefinierten Größe besteht, die durch das AddressDescriptionSize Member der WDF_CHILD_ADDRESS_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 EvtChildListAddressDescriptionDuplicate 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 DestinationAddressDescription- Struktur der Rückruffunktion).
Kopieren Sie andere Strukturmber aus der SourceAddressDescription- Struktur der Rückruffunktion in die DestinationAddressDescription- Struktur der Rückruffunktion.

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

Das Framework ruft vor dem Aufrufen der EvtChildListAddressDescriptionDuplicate Rückruffunktion eine interne Objektsperre für untergeordnete Listen ab. Die Rückruffunktion darf nur Vorgänge ausführen, die mit dem beschriebenen Duplizierungsvorgang 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.

Wenn Ihr Treiber eine EvtChildListAddressDescriptionDuplicate Rückruffunktion bereitstellt, benötigt er möglicherweise auch EvtChildListAddressDescriptionCopy und EvtChildListAddressDescriptionCleanup Rückruffunktionen.

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