Bagikan melalui


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
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:

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)

Lihat juga

EvtChildListIdentificationDescriptionCompare

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT

WDF_CHILD_LIST_ITERATOR

WDF_CHILD_LIST_ITERATOR_INIT

WDF_CHILD_RETRIEVE_INFO

WDF_RETRIEVE_CHILD_FLAGS

WdfChildListBeginIteration

WdfChildListBeginScan

WdfChildListEndIteration

WdfChildListRequestChildEject

WdfChildListRetrieveNextDevice