EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY funzione di callback (wdfchildlist.h)

Articolo
08/08/2023

[Si applica solo a KMDF]

La funzione di callback dell'evento EvtChildListAddressDescriptionCopy di un driver copia una descrizione dell'indirizzo figlio da una posizione specificata a un'altra.

Sintassi

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

Parametri

[in] ChildList

Handle per un oggetto elenco figlio del framework.

[in] SourceAddressDescription

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

[out] DestinationAddressDescription

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

Valore restituito

nessuno

Osservazioni

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

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

La funzione di callback EvtChildListAddressDescriptionCopy deve copiare il contenuto di una descrizione di origine in una descrizione di destinazione. Un driver deve fornire questa funzione di callback se i dispositivi figlio richiedono una descrizione dell'indirizzo e se il framework non può chiamare RtlCopyMemory per copiare la descrizione dell'indirizzo. Il framework non può chiamare RtlCopyMemory se la descrizione contiene puntatori a memoria aggiuntiva.

Se il driver fornisce descrizioni degli indirizzi ma non fornisce una funzione di callback EvtChildListAddressDescriptionCopy , il framework copia le descrizioni degli indirizzi chiamando RtlCopyMemory.

I passaggi seguenti descrivono uno scenario tipico:

Il driver determina che esiste un dispositivo figlio.
Il driver crea una descrizione dell'indirizzo compilando una struttura definita dal driver che contiene una struttura di WDF_CHILD_ADDRESS_DESCRIPTION_HEADER ed eventualmente allocando in modo dinamico una memoria aggiuntiva per archiviare le informazioni sugli indirizzi con dimensioni specifiche del dispositivo.
Il driver chiama WdfChildListAddOrUpdateChildDescriptionAsPresent per segnalare un dispositivo figlio, fornendo un puntatore alla descrizione dell'indirizzo.
Il framework determina che il driver aveva segnalato in precedenza il dispositivo, in modo che il framework possa aggiornare la descrizione dell'indirizzo precedente del dispositivo con nuove informazioni.
Il framework chiama la funzione di callback EvtChildListAddressDescriptionCopy (se esistente) o RtlCopyMemory per copiare le informazioni sulla descrizione del nuovo indirizzo nella descrizione dell'indirizzo esistente.

Il framework può usare RtlCopyMemory per copiare una descrizione dell'indirizzo, se la descrizione è costituita da una singola struttura con una dimensione predeterminata specificata dal membro AddressDescriptionSize della struttura WDF_CHILD_ADDRESS_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 che il driver fornisca una funzione di callback EvtChildListAddressDescriptionCopy . La funzione di callback deve eseguire le operazioni seguenti:

Nelle strutture SourceAddressDescription e DestinationAddressDescription della funzione di callback trovare i puntatori alla memoria allocata in modo dinamico.
Copiare la memoria allocata dinamicamente dall'origine alla destinazione usando i puntatori.
Copiare altri membri della struttura dalla struttura SourceAddressDescription della funzione di callback alla struttura DestinationAddressDescription della funzione di callback.

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

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

Se il driver fornisce una funzione di callback EvtChildListAddressDescriptionCopy , potrebbe essere necessaria anche funzioni di callback EvtChildListAddressDescriptionDuplicate e EvtChildListAddressDescriptionCleanup .

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