EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY Rückruffunktion (wdfchildlist.h)

2025-02-07

[Gilt nur für KMDF]

Die EvtChildListAddressDescriptionCopy Ereignisrückruffunktion kopiert eine untergeordnete Adressbeschreibung von einem angegebenen Speicherort in 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 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

Nichts

Bemerkungen

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

Das Framework kopiert Informationen von einer vom Treiber bereitgestellten Adressbeschreibung in eine andere, wenn eine vorhandene Beschreibung mit neuen Informationen aktualisiert werden muss oder wenn der Inhalt einer Adressbeschreibung an den Treiber übergeben werden muss.

Die EvtChildListAddressDescriptionCopy Rückruffunktion muss den Inhalt einer Quellbeschreibung in eine Zielbeschreibung kopieren. 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 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, indem RtlCopyMemoryaufgerufen wird.

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 bestimmt, dass der Treiber zuvor das Gerät gemeldet hatte, sodass das Framework die alte Adressbeschreibung des Geräts mit neuen Informationen aktualisieren kann.
Das Framework ruft die EvtChildListAddressDescriptionCopy Rückruffunktion (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 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 zugeordneten Speicher verweist, und Ihr Treiber muss eine EvtChildListAddressDescriptionCopy Rückruffunktion bereitstellen. Die Rückruffunktion muss folgende Aktionen ausführen:

Suchen Sie in den SourceAddressDescription- der Rückruffunktion und DestinationAddressDescription- Strukturen die Zeiger, um den Speicher dynamisch zuzuweisen.
Kopieren Sie den dynamisch zugewiesenen Speicher aus der Quelle an das Ziel, indem Sie die Zeiger verwenden.
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 EvtChildListAddressDescriptionCopy Rückruffunktion aufgerufen werden kann, ist WdfChildListGetDevice.

Das Framework erwirbt eine interne Objektsperre für untergeordnete Listen, bevor die EvtChildListAddressDescriptionCopy Rückruffunktion 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 EvtChildListAddressDescriptionDuplicate und EvtChildListAddressDescriptionCleanup Rückruffunktionen.

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