EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE funzione di callback (wdfchildlist.h)

Articolo
08/08/2023

[Si applica solo a KMDF]

La funzione di callback dell'evento EvtChildListAddressDescriptionDuplicate di un driver duplica una descrizione dell'indirizzo figlio.

Sintassi

EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE EvtWdfChildListAddressDescriptionDuplicate;

NTSTATUS EvtWdfChildListAddressDescriptionDuplicate(
  [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

La funzione di callback EvtChildListAddressDescriptionDuplicate deve restituire STATUS_SUCCESS o un altro valore di stato per cui NT_SUCCESS(status) è TRUE, se l'operazione ha esito positivo. In caso contrario, questa funzione deve restituire un valore di stato per il quale NT_SUCCESS(status) è uguale a FALSE.

Commenti

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

Il framework duplica le descrizioni degli indirizzi forniti dal driver in modo che possa avere copie interne delle descrizioni.

La funzione di callback EvtChildListAddressDescriptionDuplicate deve creare una copia duplicata di una descrizione dell'indirizzo. 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 duplicare 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 EvtChildListAddressDescriptionDuplicate , il framework duplica 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 chiama la funzione di callback EvtChildListAddressDescriptionDuplicate (se esistente) o RtlCopyMemory per duplicare la descrizione dell'indirizzo in modo che possa avere una copia interna della descrizione.

Il framework può usare RtlCopyMemory per duplicare 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 il driver debba fornire una funzione di callback EvtChildListAddressDescriptionDuplicate . La funzione di callback deve eseguire le operazioni seguenti:

Allocare memoria aggiuntiva, in genere chiamando ExAllocatePool.
Archiviare l'indirizzo della memoria allocata nella struttura di descrizione dell'indirizzo definita dal driver, ovvero la struttura DestinationAddressDescription della funzione di callback.
Copiare altri membri della struttura dalla struttura SourceAddressDescription della funzione di callback alla struttura DestinationAddressDescription della funzione di callback.

L'unico metodo dell'oggetto child-list del framework che la funzione di callback EvtChildListAddressDescriptionDuplicate di un driver può chiamare è WdfChildListGetDevice.

Il framework acquisisce un blocco di oggetti dell'elenco figlio interno prima di chiamare la funzione di callback EvtChildListAddressDescriptionDuplicate . La funzione di callback deve eseguire solo operazioni correlate all'operazione di duplicazione descritta, ad esempio la chiamata dei 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 una funzione di callback EvtChildListAddressDescriptionDuplicate , potrebbe essere necessaria anche la funzione di callback EvtChildListAddressDescriptionCopy e EvtChildListAddressDescriptionCleanup .

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