EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE funzione di callback (wdfchildlist.h)

Articolo
02/29/2024

[Si applica solo a KMDF]

La funzione di callback dell'evento EvtChildListIdentificationDescriptionCompare confronta una descrizione dell'identificazione figlio con un'altra.

Sintassi

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE EvtWdfChildListIdentificationDescriptionCompare;

BOOLEAN EvtWdfChildListIdentificationDescriptionCompare(
  [in] WDFCHILDLIST ChildList,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER FirstIdentificationDescription,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SecondIdentificationDescription
)
{...}

Parametri

[in] ChildList

Handle per un oggetto elenco figlio del framework.

[in] FirstIdentificationDescription

Puntatore a una struttura WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER che identifica la descrizione dell'identificazione figlio.

[in] SecondIdentificationDescription

Puntatore a una struttura WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER che identifica un'altra descrizione di identificazione figlio.

Valore restituito

La funzione di callback EvtChildListIdentificationDescriptionCompare deve restituire TRUE se le due descrizioni di identificazione figlio corrispondono. In caso contrario, questa funzione deve restituire FALSE.

Commenti

Se un driver del bus usa l'enumerazione dinamica, può registrare una funzione evtChildListIdentificationDescriptionCompare callback chiamando WdfFdoInitSetDefaultChildListConfig o WdfChildListCreate. Il driver può anche registrare una seconda funzione di callback evtChildListIdentificationDescriptionCompare callback quando chiama WdfChildListRetrieveNextDevice.

Il framework confronta due descrizioni di identificazione quando deve determinare se entrambe le descrizioni identificano lo stesso dispositivo.

La funzione di callback EvtChildListIdentificationDescriptionCompare deve confrontare il contenuto di due descrizioni di identificazione e restituire TRUE se corrispondono. Un driver deve fornire questa funzione di callback se il framework non può chiamare RtlCompareMemory per confrontare le descrizioni di identificazione. Il framework non può chiamare RtlCompareMemory se le descrizioni contengono puntatori a memoria aggiuntiva.

Se il driver non fornisce una funzione evtChildListIdentificationDescriptionCompare callback, il framework confronta le descrizioni di identificazione chiamando RtlCompareMemory.

I passaggi seguenti descrivono uno scenario possibile:

Il driver chiama WdfChildListRetrieveAddressDescription per ottenere la descrizione dell'indirizzo associata alla copia del framework di una descrizione di identificazione, archiviata in un elenco figlio.
Il framework attraversa l'elenco figlio. Per determinare se la descrizione di identificazione di un figlio corrisponde a quella specificata dal driver quando viene chiamata WdfChildListRetrieveAddressDescription, il framework chiama la funzione evtChildListIdentificationDescriptionCompare callback (se presente) o RtlCompareMemory.
Se le due descrizioni di identificazione corrispondono (e il confronto restituisce TRUE), il framework smette di attraversare l'elenco.
Il framework copia la descrizione dell'indirizzo in memoria fornita dal driver quando viene chiamato WdfChildListRetrieveAddressDescription.

Il framework può usare RtlCompareMemory per confrontare le descrizioni di identificazione, se ogni 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 evtChildListIdentificationDescriptionCompare callback.

Questa funzione di callback determina se due descrizioni di identificazione rappresentano lo stesso dispositivo. La funzione di callback potrebbe non dover confrontare tutti i membri della struttura per effettuare tale determinazione. Si supponga, ad esempio, che una descrizione di identificazione contenga un numero di serie e un set di identificatori hardware, come indicato di seguito:

typedef struct _PDO_IDENTIFICATION_DESCRIPTION {
  WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Header;
  ULONG DeviceSerialNumber;
  ULONG CchHardwareIds;
  PWCHAR HardwareIds;
} PDO_IDENTIFICATION_DESCRIPTION, *PPDO_IDENTIFICATION_DESCRIPTION;

In questo caso, la funzione evtChildListIdentificationDescriptionCompare callback probabilmente deve confrontare solo i membri DeviceSerialNumber per determinare se due descrizioni rappresentano lo stesso dispositivo.

Se il driver chiama WdfChildListRetrieveNextDevice per attraversare un elenco di dispositivi, è possibile fornire una funzione di callback EvtChildListIdentificationDescriptionCompare callback utilizzata dal framework quando si cerca la descrizione successiva da recuperare. Il framework cerca i dispositivi figlio che corrispondono ai flag WDF_RETRIEVE_CHILD_FLAGS tipizzato dal driver. Se un driver fornisce una funzione di callback evtChildListIdentificationDescriptionCompare callback, il framework usa la funzione callback per perfezionare la ricerca. Se il driver non fornisce una funzione di callback evtChildListIdentificationDescriptionCompare callback, il framework non chiama RtlCompareMemory- restituisce semplicemente ogni dispositivo figlio che corrisponde ai flag specificati.

L'unico metodo dell'oggetto child-list del framework che può essere chiamato dalla funzione evtChildListIdentificationDescriptionCompare callback è WdfChildListGetDevice.

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

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