Fungsi WdfChildListAddOrUpdateChildDescriptionAsPresent (wdfchildlist.h)

Artikel
02/29/2024

[Berlaku untuk KMDF saja]

Metode WdfChildListAddOrUpdateChildDescriptionAsPresent menambahkan deskripsi anak baru ke daftar anak atau memperbarui deskripsi anak yang ada.

Sintaks

NTSTATUS WdfChildListAddOrUpdateChildDescriptionAsPresent(
  [in]           WDFCHILDLIST                                 ChildList,
  [in]           PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription,
  [in, optional] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER        AddressDescription
);

Parameter

[in] ChildList

Handel ke objek daftar anak kerangka kerja.

[in] IdentificationDescription

Penunjuk ke struktur WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER yang mengidentifikasi deskripsi identifikasi anak.

[in, optional] AddressDescription

Penunjuk ke struktur WDF_CHILD_ADDRESS_DESCRIPTION_HEADER yang mengidentifikasi deskripsi alamat anak. Jika deskripsi alamat tidak diperlukan, parameter ini bisa NULL.

Nilai kembali

WdfChildListAddOrUpdateChildDescriptionAsPresent mengembalikan STATUS_SUCCESS, atau nilai status berjenis NTSTATUS lainnya 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_INVALID_DEVICE_REQUEST	Ukuran deskripsi identifikasi atau deskripsi alamat salah.
STATUS_OBJECT_NAME_EXISTS	Anak dengan deskripsi identifikasi yang disediakan sudah ada. Dalam hal ini, kerangka kerja menyalin deskripsi alamat yang disediakan ke anak yang ada.
STATUS_INSUFFICIENT_RESOURCES	Deskripsi anak dapat dialokasikan.

Metode ini mungkin juga mengembalikan nilai NTSTATUS lainnya.

Pemeriksaan bug sistem terjadi jika driver memasok handel objek yang tidak valid.

Keterangan

Metode WdfChildListAddOrUpdateChildDescriptionAsPresent mencari daftar anak yang ditentukan untuk anak yang cocok dengan deskripsi identifikasi yang disediakan. Jika kecocokan ditemukan, kerangka kerja memperbarui deskripsi alamat anak, jika disediakan, dan mengembalikan STATUS_OBJECT_NAME_EXISTS. Jika tidak ada kecocokan yang ditemukan, kerangka kerja membuat anak baru dengan menggunakan deskripsi identifikasi dan alamat yang disediakan.

Driver dapat memanggil WdfChildListAddOrUpdateChildDescriptionAsPresent untuk menambahkan atau memperbarui deskripsi anak tunggal. Kerangka kerja segera memperbarui daftar anak dan memberi tahu manajer Plug and Play (PnP) bahwa perubahan telah dilakukan.

Atau, driver dapat melakukan hal berikut:

Panggil WdfChildListBeginScan untuk menyiapkan daftar anak untuk diperbarui.
Panggil WdfChildListAddOrUpdateChildDescriptionAsPresent beberapa kali untuk menambahkan atau memperbarui deskripsi anak untuk semua anak perangkat induk.
Panggil WdfChildListEndScan untuk memproses perubahan pada daftar anak.

Jika driver menggunakan prosedur alternatif ini, kerangka kerja menunggu sampai driver memanggil WdfChildListEndScan sebelum memperbarui daftar anak dan memberi tahu manajer PnP bahwa perubahan telah dilakukan. Ketika driver Anda memanggil WdfChildListBeginScan, kerangka kerja menandai semua perangkat yang dilaporkan sebelumnya karena tidak lagi ada. Oleh karena itu, driver harus memanggil WdfChildListAddOrUpdateChildDescriptionAsPresent untuk semua anak, bukan hanya anak yang baru ditemukan.

Pada beberapa waktu setelah driver memanggil fungsi panggilan balik WdfChildListAddOrUpdateChildDescriptionAsPresent, kerangka kerja memanggil fungsi panggilan balik EvtChildListCreateDevice driver sehingga driver dapat membuat objek perangkat dengan memanggil WdfDeviceCreate.

Untuk informasi selengkapnya tentang daftar anak, lihat Enumerasi Dinamis.

Contoh

Contoh kode berikut didasarkan pada kode yang berisi sampel kmdf_fx2 . Contoh menambahkan deskripsi anak ke daftar anak default perangkat. Ini mengambil pengaturan pengalihan yang sebelumnya disimpan driver di ruang konteks objek perangkat dan kemudian memanggil WdfChildListAddOrUpdateChildDescriptionAsPresent untuk setiap sakelar yang diatur.

PDEVICE_CONTEXT  pDeviceContext;
WDFCHILDLIST  list;
UCHAR  i;
NTSTATUS  status;

pDeviceContext = GetDeviceContext(Device);
list = WdfFdoGetDefaultChildList(Device);

WdfChildListBeginScan(list);
 
for (i = 0; i < RTL_BITS_OF(UCHAR); i++) {
    if (pDeviceContext->CurrentSwitchState & (1<<i)) {
        PDO_IDENTIFICATION_DESCRIPTION description;
        WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                 &description.Header,
                                                 sizeof(description)
                                                 );
        description.SwitchNumber = i; 
 
        status = WdfChildListAddOrUpdateChildDescriptionAsPresent(
                                                 list, 
                                                 &description.Header, 
                                                 NULL
                                                 );
        if (!NT_SUCCESS(status) && (status != STATUS_OBJECT_NAME_EXISTS)) {
            break;
        }
    }
}
WdfChildListEndScan(list);

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)