Fungsi WdfChildListRetrieveNextDevice (wdfchildlist.h)
[Hanya berlaku untuk KMDF]
Metode WdfChildListRetrieveNextDevice melintasi daftar anak tertentu dan mengambil perangkat anak berikutnya yang cocok dengan kriteria yang ditentukan.
Sintaks
NTSTATUS WdfChildListRetrieveNextDevice(
[in] WDFCHILDLIST ChildList,
[in] PWDF_CHILD_LIST_ITERATOR Iterator,
[out] WDFDEVICE *Device,
[in, out] PWDF_CHILD_RETRIEVE_INFO Info
);
Parameter
[in] ChildList
Handel ke objek daftar turunan kerangka kerja.
[in] Iterator
Penunjuk ke struktur WDF_CHILD_LIST_ITERATOR yang dialokasikan pemanggil yang sama dengan yang sebelumnya disediakan driver ke WdfChildListBeginIteration.
[out] Device
Penunjuk ke lokasi yang menerima handel ke objek perangkat kerangka kerja. Nilai yang diterima adalah NULL jika parameter Iterator menentukan bendera WdfRetrievePendingChildren .
[in, out] Info
Penunjuk ke struktur WDF_CHILD_RETRIEVE_INFO yang dialokasikan penelepon. Penunjuk ini bersifat opsional dan dapat berupa NULL.
Nilai kembali
WdfChildListRetrieveNextDevice mengembalikan STATUS_SUCCESS, atau nilai status lain yang NT_SUCCESS(status) sama dengan TRUE, jika operasi berhasil. Jika tidak, metode ini mungkin mengembalikan salah satu nilai berikut:
Menampilkan kode | Deskripsi |
---|---|
|
Parameter input tidak valid. |
|
Ukuran struktur WDF_CHILD_LIST_ITERATOR yang ditentukan Iterator salah |
|
Deskripsi alamat ditentukan tetapi daftar anak tidak berisi deskripsi alamat. |
|
Kerangka kerja mencapai akhir daftar anak. |
|
Driver belum memanggil WdfChildListBeginIteration. |
Metode ini mungkin juga mengembalikan nilai NTSTATUS lainnya.
Pemeriksaan bug sistem terjadi jika driver memasok handel objek yang tidak valid.
Keterangan
Sebelum memanggil WdfChildListRetrieveNextDevice, driver Anda harus memanggil WdfChildListBeginIteration. Setelah driver selesai melintas daftar anak, driver harus memanggil WdfChildListEndIteration. Kerangka kerja kemudian memberi tahu manajer Plug and Play (PnP) tentang setiap perubahan yang dilakukan pada daftar anak.
Setiap kali driver memanggil WdfChildListRetrieveNextDevice, metode mengambil anak berikutnya yang cocok dengan kriteria pencarian berikut:
- Jenis anak harus sesuai dengan bendera WDF_RETRIEVE_CHILD_FLAGS-typed dalam struktur WDF_CHILD_LIST_ITERATOR driver.
- Jika driver menyediakan penunjuk ke fungsi panggilan balik EvtChildListIdentificationDescriptionCompare dalam struktur WDF_CHILD_RETRIEVE_INFO , fungsi panggilan balik harus mengembalikan TRUE.
Ketika WdfChildListRetrieveNextDevice menemukan kecocokan, WdfChildListRetrieveNextDevice menyalin deskripsi identifikasi anak dan deskripsi alamat ke dalam struktur WDF_CHILD_RETRIEVE_INFO driver, jika penunjuk yang ditentukan parameter Info bukan NULL. (Perhatikan bahwa operasi ini menimpa deskripsi identifikasi input driver.) Metode ini juga menempatkan handel ke objek perangkat anak di lokasi yang diidentifikasi oleh parameter Perangkat .
Untuk informasi selengkapnya tentang daftar anak, lihat Enumerasi Dinamis.
Contoh
Contoh kode berikut menginformasikan kerangka kerja bahwa semua turunan perangkat induk dikeluarkan. Contohnya mendapatkan daftar anak default perangkat dan menelusuri daftar. Ini memperoleh deskriptor identifikasi setiap anak, dan meneruskan setiap deskriptor identifikasi ke WdfChildListRequestChildEject.
WDF_CHILD_LIST_ITERATOR iterator;
WDFDEVICE hChild;
NTSTATUS status = STATUS_INVALID_PARAMETER;
WDFCHILDLIST list;
WDF_CHILD_RETRIEVE_INFO childInfo;
PDO_IDENTIFICATION_DESCRIPTION description;
BOOLEAN ret;
list = WdfFdoGetDefaultChildList(Device);
WDF_CHILD_LIST_ITERATOR_INIT(
&iterator,
WdfRetrievePresentChildren
);
WdfChildListBeginIteration(
list,
&iterator
);
for (;;) {
WDF_CHILD_RETRIEVE_INFO_INIT(
&childInfo,
&description.Header
);
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
&description.Header,
sizeof(description)
);
status = WdfChildListRetrieveNextDevice(
list,
&iterator,
&hChild,
&childInfo
);
if (!NT_SUCCESS(status) || status == STATUS_NO_MORE_ENTRIES) {
break;
}
ASSERT(childInfo.Status == WdfChildListRetrieveDeviceSuccess);
ret = WdfChildListRequestChildEject(
list,
&description.Header
);
if(!ret) {
WDFVERIFY(ret);
}
}
WdfChildListEndIteration(
list,
&iterator
);
if (status == STATUS_NO_MORE_ENTRIES) {
status = STATUS_SUCCESS;
}
return status;
Persyaratan
Persyaratan | Nilai |
---|---|
Target Platform | Universal |
Versi KMDF minimum | 1,0 |
Header | wdfchildlist.h (termasuk Wdf.h) |
Pustaka | Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.) |
IRQL | <= DISPATCH_LEVEL |
Aturan kepatuhan DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |
Lihat juga
EvtChildListIdentificationDescriptionCompare
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk