EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY Rückruffunktion (wdfchildlist.h)

Artikel
08/08/2023

[Gilt nur für KMDF]

Die EvtChildListAddressDescriptionCopy-Ereignisrückruffunktion eines Treibers kopiert eine untergeordnete Adressbeschreibung von einem angegebenen Speicherort an einen anderen.

Syntax

EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY EvtWdfChildListAddressDescriptionCopy;

void EvtWdfChildListAddressDescriptionCopy(
  [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

Keine

Bemerkungen

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

Das Framework kopiert Informationen aus einer vom Treiber bereitgestellten Adressbeschreibung in eine andere, wenn es eine vorhandene Beschreibung mit neuen Informationen aktualisieren oder den Inhalt einer Adressbeschreibung an den Treiber übergeben muss.

Die Rückruffunktion EvtChildListAddressDescriptionCopy muss den Inhalt einer Quellbeschreibung in eine Zielbeschreibung kopieren. 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 kopieren. (Das Framework kann RtlCopyMemory nicht aufrufen, wenn die Beschreibung Zeiger auf zusätzlichen Arbeitsspeicher enthält.)

Wenn Ihr Treiber Adressbeschreibungen bereitstellt, aber keine EvtChildListAddressDescriptionCopy-Rückruffunktion bereitstellt, kopiert 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 ermittelt, dass der Treiber das Gerät zuvor gemeldet hat, sodass das Framework die alte Adressbeschreibung des Geräts mit neuen Informationen aktualisieren kann.
Das Framework ruft die Rückruffunktion EvtChildListAddressDescriptionCopy (sofern vorhanden) oder RtlCopyMemory auf, um die neuen Adressbeschreibungsinformationen in die vorhandene Adressbeschreibung zu kopieren.

Das Framework kann RtlCopyMemory verwenden, um eine Adressbeschreibung zu kopieren, 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 eine EvtChildListAddressDescriptionCopy-Rückruffunktion bereitstellen muss. Die Rückruffunktion muss folgende Aktionen ausführen:

Suchen Sie in den Strukturen SourceAddressDescription und DestinationAddressDescription der Rückruffunktion nach den Zeigern auf dynamisch zugeordneten Arbeitsspeicher.
Kopieren Sie den dynamisch zugeordneten Arbeitsspeicher mithilfe der Zeiger aus der Quelle in das Ziel.
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 EvtChildListAddressDescriptionCopy-Rückruffunktion eines Treibers aufgerufen werden kann, ist WdfChildListGetDevice.

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

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