EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COPY funzione di callback (wdfchildlist.h)

Articolo
02/26/2024

[Si applica solo a KMDF]

La funzione di callback dell'evento EvtChildListIdentificationDescriptionCopy copia una descrizione dell'identificazione figlio da una posizione specificata a un'altra.

Sintassi

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
)
{...}

Parametri

[in] ChildList

Handle per un oggetto elenco figlio del framework.

[in] SourceIdentificationDescription

Puntatore a una struttura WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER che identifica la posizione di origine della descrizione dell'identificazione figlio.

[out] DestinationIdentificationDescription

Puntatore a una struttura WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER che identifica la posizione di destinazione della descrizione dell'identificazione figlio.

Valore restituito

nessuno

Osservazioni

Se un driver del bus usa l'enumerazione dinamica, può registrare una funzione di callback EvtChildListIdentificationDescriptionCopy chiamando WdfFdoInitSetDefaultChildListConfig o WdfChildListCreate.

Il framework copia le informazioni da una descrizione di identificazione fornita dal driver a un'altra quando deve aggiornare una descrizione esistente con nuove informazioni o quando deve passare il contenuto di una descrizione di identificazione al driver.

La funzione callback EvtChildListIdentificationDescriptionCopy deve copiare il contenuto di una descrizione di origine in una descrizione di destinazione. Un driver deve fornire questa funzione di callback se il framework non può chiamare RtlCopyMemory per copiare la descrizione dell'identificazione. Il framework non può chiamare RtlCopyMemory se la descrizione contiene puntatori a memoria aggiuntiva.

Se il driver non fornisce una funzione di callback EvtChildListIdentificationDescriptionCopy , il framework copia le descrizioni di identificazione chiamando RtlCopyMemory.

I passaggi seguenti descrivono uno scenario possibile:

Il driver che attraversa un elenco figlio chiama WdfChildListRetrieveNextDevice. Il driver fornisce una struttura WDF_CHILD_RETRIEVE_INFO in modo che possa ricevere la descrizione di identificazione del dispositivo figlio.
Il framework chiama la funzione di callback EvtChildListIdentificationDescriptionCopy (se esistente) o RtlCopyMemory per copiare la descrizione dell'identificazione del dispositivo. L'origine dell'operazione di copia è la copia interna del framework della descrizione. La destinazione è memoria allocata dal driver e identificata nella relativa struttura WDF_CHILD_RETRIEVE_INFO.

Il framework può usare RtlCopyMemory per copiare una descrizione di identificazione, se la descrizione è costituita da una singola struttura con dimensioni predeterminate specificate dal membro IdentificationDescriptionSize della struttura WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER . Tuttavia, a volte la descrizione deve contenere anche informazioni aggiuntive archiviate in memoria allocata dinamicamente. In questo caso, in genere si definirà una struttura di descrizione in modo che un membro punti alla memoria allocata dinamicamente e il driver deve fornire una funzione di callback EvtChildListIdentificationDescriptionCopy . La funzione callback deve eseguire le operazioni seguenti:

Nelle strutture SourceIdentificationDescription e DestinationIdentificationDescription della funzione callback trovare i puntatori alla memoria allocata dinamicamente.
Copiare la memoria allocata dinamicamente dall'origine alla destinazione usando i puntatori.
Copiare altri membri della struttura dalla struttura SourceIdentificationDescription della funzione callback alla struttura DestinationIdentificationDescription della funzione callback.

L'unico metodo dell'oggetto dell'elenco figlio del framework che la funzione di callback EvtChildListIdentificationDescriptionCopy può chiamare è WdfChildListGetDevice.

Il framework acquisisce un blocco dell'oggetto elenco figlio interno prima di chiamare la funzione di callback EvtChildListIdentificationDescriptionCopy . La funzione di callback deve eseguire solo operazioni correlate all'operazione di copia, ad esempio chiamare i metodi dell'oggetto memoria del framework e accedere allo spazio di contesto degli oggetti. Non deve chiamare metodi che accedono ad altri driver.

Se il driver fornisce una funzione di callback EvtChildListIdentificationDescriptionCopy, potrebbe essere necessaria anche funzioni di callback EvtChildListIdentificationDescriptionDuplicate, EvtChildListIdentificationDescriptionCompare e EvtChildListIdentificationDescriptionCleanup.

Per altre informazioni sull'enumerazione dinamica, vedere Enumerazione dei dispositivi in un bus.