Fungsi WdfCollectionAdd (wdfcollection.h)

  • Artikel

[Berlaku untuk KMDF dan UMDF]

Metode WdfCollectionAdd menambahkan objek kerangka kerja tertentu ke koleksi objek.

Sintaks

NTSTATUS WdfCollectionAdd(
  [in] WDFCOLLECTION Collection,
  [in] WDFOBJECT     Object
);

Parameter

[in] Collection

Handel ke objek koleksi.

[in] Object

Handel ke objek kerangka kerja yang akan ditambahkan ke koleksi.

Nilai kembali

WdfCollectionAdd mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini mungkin mengembalikan salah satu nilai berikut:

Menampilkan kode Deskripsi
STATUS_UNSUCCESSFUL
 Objek yang ditentukan tidak dapat ditambahkan ke koleksi yang ditentukan.
 

Metode ini mungkin juga mengembalikan nilai NTSTATUS lainnya.

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Keterangan

Metode WdfCollectionAdd menambahkan objek yang ditentukan ke akhir kumpulan objek yang dikandung koleksi. Ketika WdfCollectionAdd menambahkan objek ke koleksi, WdfCollectionAdd menambah jumlah referensi objek. Driver Anda dapat memanggil WdfCollectionRemove atau WdfCollectionRemoveItem untuk menghapus objek dan mengurangi jumlah referensinya.

Untuk informasi selengkapnya tentang koleksi objek, lihat Kumpulan Objek Kerangka Kerja.

Contoh

Contoh kode berikut membuat objek koleksi lalu menambahkan sekumpulan objek permintaan yang dibuat driver ke koleksi.

WDF_OBJECT_ATTRIBUTES  attributes;
NTSTATUS  status;
WDFCOLLECTION  hCollection = NULL;
WDFREQUEST  subRequest = NULL;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = Request;
status = WdfCollectionCreate(
                             &attributes,
                             &hCollection
                             );
if (!NT_SUCCESS(status)) {
    goto Exit;
}

for (i = 0; i < numSubRequests; i++) {
    WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
    WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                           &attributes,
                                           SUB_REQUEST_CONTEXT
                                           );
    status = WdfRequestCreate(
                              &attributes,
                              WdfUsbTargetDeviceGetIoTarget(deviceContext->WdfUsbTargetDevice),
                              &subRequest
                              );
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    status = WdfCollectionAdd(
                              hCollection,
                              subRequest
                              );
    if (!NT_SUCCESS(status)) {
        WdfObjectDelete(subRequest);
        goto Exit;
    }
}

Persyaratan

Persyaratan Nilai
Target Platform Universal
Versi KMDF minimum 1,0
Versi UMDF minimum 2.0
Header wdfcollection.h (termasuk Wdf.h)
Pustaka Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL <= DISPATCH_LEVEL
Aturan kepatuhan DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Lihat juga

WdfCollectionBuat

WdfCollectionRemove

WdfCollectionRemoveItem