EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE fungsi panggilan balik (wdfchildlist.h)

Artikel
02/29/2024

[Hanya berlaku untuk KMDF]

Fungsi panggilan balik peristiwa EvtChildListIdentificationDescriptionDuplicate driver menduplikasi deskripsi identifikasi anak.

Sintaks

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

Parameter

[in] ChildList

Handel ke objek daftar turunan kerangka kerja.

[in] SourceIdentificationDescription

Penunjuk ke struktur WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER yang mengidentifikasi lokasi sumber deskripsi identifikasi anak.

[out] DestinationIdentificationDescription

Penunjuk ke struktur WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER yang mengidentifikasi lokasi tujuan deskripsi identifikasi anak duplikat.

Menampilkan nilai

Fungsi panggilan balik EvtChildListIdentificationDescriptionDuplicate harus mengembalikan STATUS_SUCCESS, atau nilai status lain yang NT_SUCCESS(statusnya) sama dengan TRUE, jika operasi berhasil. Jika tidak, fungsi panggilan balik ini harus mengembalikan nilai status yang NT_SUCCESS(status) sama dengan FALSE.

Keterangan

Jika driver bus menggunakan enumerasi dinamis, driver dapat mendaftarkan fungsi panggilan balik EvtChildListIdentificationDescriptionDuplicate dengan memanggil WdfFdoInitSetDefaultChildListConfig atau WdfChildListCreate.

Kerangka kerja ini menduplikasi deskripsi identifikasi yang disediakan driver sehingga dapat memiliki salinan internal deskripsi.

Fungsi panggilan balik EvtChildListIdentificationDescriptionDuplicate harus membuat salinan duplikat deskripsi identifikasi. Driver harus menyediakan fungsi panggilan balik ini jika kerangka kerja tidak dapat memanggil RtlCopyMemory untuk menduplikasi deskripsi identifikasi. (Kerangka kerja tidak dapat memanggil RtlCopyMemory jika deskripsi berisi pointer ke memori tambahan.)

Jika driver Anda tidak menyediakan fungsi panggilan balik EvtChildListIdentificationDescriptionDuplicate , kerangka kerja menduplikasi deskripsi identifikasi dengan memanggil RtlCopyMemory.

Langkah-langkah berikut menjelaskan skenario umum:

Driver menentukan bahwa ada perangkat anak.
Driver membuat deskripsi identifikasi dengan mengisi struktur yang ditentukan driver yang berisi struktur WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER dan mungkin dengan mengalokasikan memori tambahan secara dinamis untuk menyimpan informasi identifikasi yang memiliki ukuran khusus perangkat.
Driver memanggil WdfChildListAddOrUpdateChildDescriptionAsPresent untuk melaporkan perangkat anak, menyediakan pointer ke deskripsi identifikasi.
Kerangka kerja memanggil fungsi panggilan balik EvtChildListIdentificationDescriptionDuplicate (jika ada) atau RtlCopyMemory untuk menduplikasi deskripsi identifikasi sehingga dapat memiliki salinan internal deskripsi.

Kerangka kerja dapat menggunakan RtlCopyMemory untuk menduplikasi deskripsi identifikasi, jika deskripsi terdiri dari struktur tunggal 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 EvtChildListIdentificationDescriptionDuplicate . Fungsi panggilan balik harus melakukan hal berikut:

Alokasikan memori tambahan, biasanya dengan memanggil ExAllocatePool.
Simpan alamat memori yang dialokasikan dalam struktur deskripsi alamat yang ditentukan driver (yaitu, struktur DestinationIdentificationDescription fungsi panggilan balik).
Salin anggota struktur lain dari struktur SourceIdentificationDescription fungsi panggilan balik ke struktur DestinationIdentificationDescription fungsi panggilan balik.

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

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

Jika driver Anda menyediakan fungsi panggilan balik EvtChildListIdentificationDescriptionDuplicate , mungkin juga memerlukan fungsi panggilan balik EvtChildListIdentificationDescriptionCopy, EvtChildListIdentificationDescriptionCompare, dan EvtChildListIdentificationDescriptionCleanup .

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