EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY funzione di callback (wdfchildlist.h)

Articolo
02/07/2025

[Si applica solo a KMDF]

La funzione di callback di un driver EvtChildListAddressDescriptionCopy 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 'enumerazione dinamica, può registrare un EvtChildListAddressDescriptionCopy funzione di callback 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 EvtChildListAddressDescriptionCopy funzione di callback 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 un EvtChildListAddressDescriptionCopy funzione di callback, 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 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 EvtChildListAddressDescriptionCopy funzione di callback (se esistente) o RtlCopyMemory per copiare le informazioni sulla nuova descrizione dell'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 AddressDescriptionSize membro 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 il driver deve fornire un EvtChildListAddressDescriptionCopy funzione di callback. La funzione di callback deve eseguire le operazioni seguenti:

Nella sourceAddressDescription della funzione di callback e strutture DestinationAddressDescription individuare 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 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 può chiamare è WdfChildListGetDevice.

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

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

Per altre informazioni sull'enumerazione dinamica, vedere Enumerating the Devices on a Bus.