EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE fungsi panggilan balik (wdfchildlist.h)

Artikel
03/08/2023

[Berlaku untuk KMDF saja]

Fungsi panggilan balik peristiwa EvtChildListIdentificationDescriptionCompare driver membandingkan satu deskripsi identifikasi anak dengan yang lain.

Sintaks

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
)
{...}

Parameter

[in] ChildList

Handel ke objek daftar turunan kerangka kerja.

[in] FirstIdentificationDescription

Penunjuk ke struktur WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER yang mengidentifikasi satu deskripsi identifikasi anak.

[in] SecondIdentificationDescription

Penunjuk ke struktur WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER yang mengidentifikasi deskripsi identifikasi anak lain.

Nilai kembali

Fungsi panggilan balik EvtChildListIdentificationDescriptionCompare harus mengembalikan TRUE jika dua deskripsi identifikasi anak cocok. Jika tidak, fungsi ini harus mengembalikan FALSE.

Keterangan

Jika driver bus menggunakan enumerasi dinamis, driver dapat mendaftarkan fungsi panggilan balik EvtChildListIdentificationDescriptionCompare dengan memanggil WdfFdoInitSetDefaultChildListConfig atau WdfChildListCreate. Driver juga dapat mendaftarkan fungsi panggilan balik EvtChildListIdentificationDescriptionCompare kedua kasus khusus saat memanggil WdfChildListRetrieveNextDevice.

Kerangka kerja membandingkan dua deskripsi identifikasi ketika harus menentukan apakah kedua deskripsi mengidentifikasi perangkat yang sama.

Fungsi panggilan balik EvtChildListIdentificationDescriptionCompare harus membandingkan konten dua deskripsi identifikasi dan mengembalikan TRUE jika cocok. Driver harus menyediakan fungsi panggilan balik ini jika kerangka kerja tidak dapat memanggil RtlCompareMemory untuk membandingkan deskripsi identifikasi. (Kerangka kerja tidak dapat memanggil RtlCompareMemory jika deskripsi berisi pointer ke memori tambahan.)

Jika driver Anda tidak menyediakan fungsi panggilan balik EvtChildListIdentificationDescriptionCompare , kerangka kerja membandingkan deskripsi identifikasi dengan memanggil RtlCompareMemory.

Langkah-langkah berikut menjelaskan kemungkinan skenario:

Driver memanggil WdfChildListRetrieveAddressDescription untuk mendapatkan deskripsi alamat yang terkait dengan salinan kerangka kerja deskripsi identifikasi, yang disimpan dalam daftar anak.
Kerangka kerja melintasi daftar anak. Untuk menentukan apakah deskripsi identifikasi anak cocok dengan yang ditentukan driver saat disebut WdfChildListRetrieveAddressDescription, kerangka kerja memanggil fungsi panggilan balik EvtChildListIdentificationDescriptionCompare (jika ada) atau RtlCompareMemory.
Jika dua deskripsi identifikasi cocok (dan perbandingan mengembalikan TRUE), kerangka kerja berhenti melintasi daftar.
Kerangka kerja menyalin deskripsi alamat ke dalam memori yang disediakan driver ketika disebut WdfChildListRetrieveAddressDescription.

Kerangka kerja dapat menggunakan RtlCompareMemory untuk membandingkan deskripsi identifikasi, jika setiap deskripsi terdiri dari satu struktur dengan ukuran yang telah ditentukan yang ditentukan oleh anggota IdentificationDescriptionSize dari struktur WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER . Namun, terkadang deskripsi juga harus berisi informasi tambahan yang disimpan dalam memori yang dialokasikan secara dinamis. Dalam hal ini, Anda biasanya akan menentukan struktur deskripsi sehingga anggota menunjuk ke memori yang dialokasikan secara dinamis, dan driver Anda harus menyediakan fungsi panggilan balik EvtChildListIdentificationDescriptionCompare .

Fungsi panggilan balik ini menentukan apakah dua deskripsi identifikasi mewakili perangkat yang sama. Fungsi panggilan balik mungkin tidak perlu membandingkan semua anggota struktur untuk membuat penentuan tersebut. Misalnya, deskripsi identifikasi berisi nomor seri dan sekumpulan pengidentifikasi perangkat keras, sebagai berikut:

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

Dalam hal ini, fungsi panggilan balik EvtChildListIdentificationDescriptionCompare mungkin hanya harus membandingkan anggota DeviceSerialNumber untuk menentukan apakah dua deskripsi mewakili perangkat yang sama.

Jika driver Anda memanggil WdfChildListRetrieveNextDevice untuk melintasi daftar perangkat, Anda dapat menyediakan fungsi panggilan balik EvtChildListIdentificationDescriptionCompare tambahan yang digunakan kerangka kerja saat mencari deskripsi berikutnya untuk diambil. Kerangka kerja mencari perangkat anak yang cocok dengan bendera WDF_RETRIEVE_CHILD_FLAGS yang disediakan driver. Jika driver menyediakan fungsi panggilan balik EvtChildListIdentificationDescriptionCompare khusus, kerangka kerja menggunakan fungsi panggilan balik untuk memperbaiki pencarian. Jika driver tidak menyediakan fungsi panggilan balik EvtChildListIdentificationDescriptionCompare khusus, kerangka kerja tidak memanggil RtlCompareMemory--hanya mengembalikan setiap perangkat anak yang cocok dengan bendera yang ditentukan.

Satu-satunya metode objek daftar anak kerangka kerja yang dapat dipanggil oleh fungsi panggilan balik EvtChildListIdentificationDescriptionCompare driver adalah WdfChildListGetDevice.

Kerangka kerja memperoleh kunci objek daftar anak internal sebelum memanggil fungsi panggilan balik EvtChildListIdentificationDescriptionCompareEvtChildListIdentificationDescriptionCompare . Fungsi panggilan balik hanya boleh melakukan operasi yang terkait dengan operasi perbandingan, seperti memanggil metode objek memori kerangka kerja dan mengakses ruang konteks objek. Ini tidak boleh memanggil metode yang mengakses driver lain.

Untuk informasi selengkapnya tentang enumerasi dinamis, lihat Menghitung Perangkat di Bus.