Fungsi WdfChildListRetrieveNextDevice (wdfchildlist.h)

Artikel
08/08/2023

[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
STATUS_INVALID_PARAMETER	Parameter input tidak valid.
STATUS_INFO_LENGTH_MISMATCH	Ukuran struktur WDF_CHILD_LIST_ITERATOR yang ditentukan Iterator salah
STATUS_INVALID_DEVICE_REQUEST	Deskripsi alamat ditentukan tetapi daftar anak tidak berisi deskripsi alamat.
STATUS_NO_MORE_ENTRIES	Kerangka kerja mencapai akhir daftar anak.
STATUS_INVALID_DEVICE_STATE	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.

Jika driver menyediakan fungsi panggilan balik EvtChildListIdentificationDescriptionCompare , driver juga harus memberikan deskripsi identifikasi dalam struktur WDF_CHILD_RETRIEVE_INFO. Kerangka kerja menggunakan fungsi panggilan balik untuk membandingkan deskriptor identifikasi yang diteruskan dengan deskripsi anak dalam daftar anak, jika bendera yang WDF_RETRIEVE_CHILD_FLAGS ketik menunjukkan bahwa anak tersebut adalah kandidat yang cocok. Jika fungsi panggilan balik mengembalikan TRUE, kecocokan berhasil. Jika fungsi panggilan balik mengembalikan FALSE, kerangka kerja mencari kandidat lain.

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)