EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE funzione di callback (wdfchildlist.h)

Articolo
02/29/2024

[Si applica solo a KMDF]

La funzione di callback dell'evento EvtChildListIdentificationDescriptionDuplicate di un driver duplica una descrizione dell'identificazione figlio.

Sintassi

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE EvtWdfChildListIdentificationDescriptionDuplicate;

NTSTATUS EvtWdfChildListIdentificationDescriptionDuplicate(
  [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 duplicata.

Valore restituito

La funzione di callback EvtChildListIdentificationDescriptionDuplicate deve restituire STATUS_SUCCESS o un altro valore di stato per il quale NT_SUCCESS(status) è true, se l'operazione ha esito positivo. In caso contrario, questa funzione di callback 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 EvtChildListIdentificationDescriptionDuplicate chiamando WdfFdoInitSetDefaultChildListConfig o WdfChildListCreate.

Il framework duplica le descrizioni di identificazione fornite dal driver in modo che possa avere copie interne delle descrizioni.

La funzione di callback EvtChildListIdentificationDescriptionDuplicate deve creare una copia duplicata di una descrizione di identificazione. Un driver deve fornire questa funzione di callback se il framework non può chiamare RtlCopyMemory per duplicare 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 EvtChildListIdentificationDescriptionDuplicate , il framework duplica le descrizioni di identificazione chiamando RtlCopyMemory.

I passaggi seguenti descrivono uno scenario tipico:

Il driver determina che esiste un dispositivo figlio.
Il driver crea una descrizione di identificazione compilando una struttura definita dal driver che contiene una struttura WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER ed eventualmente allocando dinamicamente la memoria aggiuntiva per archiviare le informazioni di identificazione con dimensioni specifiche del dispositivo.
Il driver chiama WdfChildListAddOrUpdateChildDescriptionAsPresent per segnalare un dispositivo figlio, fornendo un puntatore alla descrizione dell'identificazione.
Il framework chiama la funzione di callback EvtChildListIdentificationDescriptionDuplicate (se esistente) o RtlCopyMemory per duplicare la descrizione dell'identificazione in modo che possa avere una copia interna della descrizione.

Il framework può usare RtlCopyMemory per duplicare una descrizione di identificazione, se la descrizione è costituita da una singola struttura con una dimensione predeterminata specificata 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 che il driver fornisca una funzione di callback EvtChildListIdentificationDescriptionDuplicate . 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 DestinationIdentificationDescription della funzione di callback.
Copiare altri membri della struttura dalla struttura SourceIdentificationDescription della funzione di callback alla struttura DestinationIdentificationDescription della funzione di callback.

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

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

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

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