EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE Rückruffunktion (wdfchildlist.h)

Artikel
02/29/2024

[Gilt nur für KMDF]

Die EvtChildListAddressDescriptionDuplicate-Ereignisrückruffunktion eines Treibers 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-Objekt mit untergeordneter Liste.

[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 Rückruffunktion EvtChildListAddressDescriptionDuplicate muss STATUS_SUCCESS oder einen anderen status-Wert zurückgeben, für den NT_SUCCESS(status) true ist, wenn der Vorgang erfolgreich ist. Andernfalls muss diese Funktion einen status Wert zurückgeben, für den NT_SUCCESS(status) gleich FALSE ist.

Hinweise

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

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

Die Rückruffunktion EvtChildListAddressDescriptionDuplicate muss eine duplizierte Kopie einer Adressbeschreibung erstellen. Ein Treiber muss diese Rückruffunktion bereitstellen, 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.

In den folgenden Schritten wird ein typisches Szenario beschrieben:

Der Treiber bestimmt, dass ein untergeordnetes Gerät vorhanden ist.
Der Treiber erstellt eine Adressbeschreibung, indem er eine treiberdefinierte Struktur eingibt, die eine WDF_CHILD_ADDRESS_DESCRIPTION_HEADER-Struktur enthält, und möglicherweise durch dynamische Zuweisung 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 und einen Zeiger auf die Adressbeschreibung anzugeben.
Das Framework ruft die Rückruffunktion EvtChildListAddressDescriptionDuplicate (sofern vorhanden) oder RtlCopyMemory auf, um die Adressbeschreibung zu duplizieren, sodass sie eine interne Kopie der Beschreibung haben 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 vom 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 Arbeitsspeicher gespeichert sind. In diesem Fall definieren Sie in der Regel eine Beschreibungsstruktur, sodass ein Member auf den dynamisch zugeordneten Speicher zeigt, 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 zugeordneten Speichers in der vom Treiber definierten Adressbeschreibungsstruktur (d. a. in der DestinationAddressDescription-Struktur der Rückruffunktion).
Kopieren Sie andere Strukturmember aus der SourceAddressDescription-Struktur der Rückruffunktion in die DestinationAddressDescription-Struktur der Rückruffunktion.

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

Das Framework ruft eine interne Objektsperre für untergeordnete Listen ab, bevor die Rückruffunktion EvtChildListAddressDescriptionDuplicate aufgerufen wird . Die Rückruffunktion darf nur Vorgänge ausführen, die sich auf den beschriebenen 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 die Rückruffunktion EvtChildListAddressDescriptionDuplicate bereitstellt, benötigt er möglicherweise auch die Rückruffunktionen EvtChildListAddressDescriptionCopy und EvtChildListAddressDescriptionCleanup .

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