EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE funzione di callback (wdfchildlist.h)

Articolo
02/07/2025

[Si applica solo a KMDF]

La di un driver EvtChildListIdentificationDescriptionCompare funzione di callback degli eventi 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 EvtChildListIdentificationDescriptionCompare funzione di callback deve restituire TRUE se le due descrizioni di identificazione figlio corrispondono. In caso contrario, questa funzione deve restituire FALSE.

Osservazioni

Se un driver del bus usa 'enumerazione dinamica, può registrare un EvtChildListIdentificationDescriptionCompare funzione di callback chiamando WdfFdoInitSetDefaultChildListConfig o WdfChildListCreate. Il driver può anche registrare un secondo caso speciale EvtChildListIdentificationDescriptionCompare funzione di 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 un EvtChildListIdentificationDescriptionCompare funzione di 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 ha chiamato WdfChildListRetrieveAddressDescription, il framework chiama il EvtChildListIdentificationDescriptionCompare funzione di callback (se esistente) 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 ha 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 IdentificationDescriptionSize membro 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 un EvtChildListIdentificationDescriptionCompare funzione di 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 determinare 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 di callback EvtChildListIdentificationDescriptionCompare 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 un aggiuntivo EvtChildListIdentificationDescriptionCompare funzione di callback usata dal framework quando si cerca la descrizione successiva da recuperare. Il framework cerca i dispositivi figlio che corrispondono ai flag forniti dal driver WDF_RETRIEVE_CHILD_FLAGStipizzato. Se un driver fornisce un speciale EvtChildListIdentificationDescriptionCompare funzione di callback, il framework usa la funzione di callback per perfezionare la ricerca. Se il driver non fornisce una speciale EvtChildListIdentificationDescriptionCompare funzione di callback, il framework non chiamare RtlCompareMemory, semplicemente restituisce ogni dispositivo figlio che corrisponde ai flag specificati.

L'unico metodo a oggetti dell'elenco figlio framework che la funzione di callback di un driver EvtChildListIdentificationDescriptionCompare funzione di callback è WdfChildListGetDevice.

Il framework acquisisce un blocco dell'oggetto elenco figlio interno prima di chiamare la EvtChildListIdentificationDescriptionCompareEvtChildListIdentificationDescriptionCompare funzione di callback. La funzione di callback deve eseguire solo operazioni correlate all'operazione di confronto, 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.

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