EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COPY Rückruffunktion (wdfchildlist.h)

[Gilt nur für KMDF]

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

Syntax

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COPY EvtWdfChildListIdentificationDescriptionCopy;

void EvtWdfChildListIdentificationDescriptionCopy(
  [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 Frameworkobjekt mit untergeordneter Liste.

[in] SourceIdentificationDescription

Ein Zeiger auf eine WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER-Struktur , die den Quellspeicherort der untergeordneten Identifikationsbeschreibung identifiziert.

[out] DestinationIdentificationDescription

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

Rückgabewert

Keine

Bemerkungen

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

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

Die Rückruffunktion EvtChildListIdentificationDescriptionCopy muss den Inhalt einer Quellbeschreibung in eine Zielbeschreibung kopieren. Ein Treiber muss diese Rückruffunktion bereitstellen, wenn das Framework rtlCopyMemory nicht aufrufen kann, um die Identifikationsbeschreibung zu kopieren. (Das Framework kann RtlCopyMemory nicht aufrufen, wenn die Beschreibung Zeiger auf zusätzlichen Arbeitsspeicher enthält.)

Wenn Ihr Treiber keine EvtChildListIdentificationDescriptionCopy-Rückruffunktion bereitstellt, kopiert das Framework Identifikationsbeschreibungen durch Aufrufen von RtlCopyMemory.

In den folgenden Schritten wird ein mögliches Szenario beschrieben:

1. Der Treiber, der eine untergeordnete Liste durchläuft, ruft WdfChildListRetrieveNextDevice auf. Der Treiber stellt eine WDF_CHILD_RETRIEVE_INFO-Struktur bereit, damit er die Identifikationsbeschreibung des untergeordneten Geräts erhalten kann.
2. Das Framework ruft die Rückruffunktion EvtChildListIdentificationDescriptionCopy (sofern vorhanden) oder RtlCopyMemory auf, um die Identifikationsbeschreibung des Geräts zu kopieren. Die Quelle des Kopiervorgangs ist die interne Kopie der Beschreibung des Frameworks. Das Ziel ist der Speicher, den der Treiber in seiner WDF_CHILD_RETRIEVE_INFO Struktur zugewiesen und identifiziert hat.

Das Framework kann RtlCopyMemory verwenden, um eine Identifikationsbeschreibung zu kopieren, wenn die Beschreibung aus einer einzelnen Struktur mit einer vordefinierten Größe besteht, die vom 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 Arbeitsspeicher gespeichert werden. In diesem Fall definieren Sie in der Regel eine Beschreibungsstruktur, sodass ein Member auf den dynamisch zugeordneten Arbeitsspeicher verweist, und Ihr Treiber muss eine EvtChildListIdentificationDescriptionCopy-Rückruffunktion bereitstellen. Die Rückruffunktion muss Folgendes ausführen:

1. Suchen Sie in den Strukturen SourceIdentificationDescription und DestinationIdentificationDescription der Rückruffunktion nach den Zeigern auf dynamisch zugeordneten Arbeitsspeicher.
2. Kopieren Sie den dynamisch zugeordneten Arbeitsspeicher mit den Zeigern von der Quelle an das Ziel.
3. Kopieren Sie andere Strukturmember aus der SourceIdentificationDescription-Struktur der Rückruffunktion in die DestinationIdentificationDescription-Struktur der Rückruffunktion.

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

Das Framework ruft eine interne Objektsperre für untergeordnete Listen ab, bevor die Rückruffunktion EvtChildListIdentificationDescriptionCopy aufgerufen wird. Die Rückruffunktion darf nur Vorgänge ausführen, die sich auf den Kopiervorgang beziehen, z. B. das Aufrufen von Framework-Speicherobjektmethoden und den Zugriff auf Objektkontextbereich. Methoden, die auf andere Treiber zugreifen, dürfen nicht aufgerufen werden.

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

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

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
Kopfzeile	wdfchildlist.h (einschließen von Wdf.h)
IRQL	<= DISPATCH_LEVEL

Weitere Informationen

EvtChildListIdentificationDescriptionCleanup

EvtChildListIdentificationDescriptionCompare

EvtChildListIdentificationDescriptionDuplicate

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER

WdfChildListCreate

WdfChildListGetDevice

WdfFdoInitSetDefaultChildListConfig