Kumpulan Objek Kerangka Kerja

Driver dapat mengelompokkan objek kerangka kerja ke dalam koleksi yang diwakili oleh objek pengumpulan kerangka kerja.

Misalnya, jika driver menerima objek permintaan kerangka kerja yang mewakili permintaan I/O besar, driver mungkin harus memecah permintaan besar menjadi permintaan yang lebih kecil yang dapat dikirim ke target I/O. Untuk memecah permintaan besar menjadi yang lebih kecil, driver harus membuat sekumpulan objek permintaan yang mewakili permintaan yang lebih kecil. Untuk melacak objek permintaan yang dibuat driver ini, driver mungkin membuat objek koleksi dan menambahkannya ke koleksi.

Biasanya, objek dalam koleksi objek terdiri dari satu jenis objek kerangka kerja, tetapi driver dapat membuat koleksi yang terdiri dari berbagai jenis objek.

Driver Anda juga dapat membuat koleksi. Artinya, koleksi dapat terdiri dari satu set objek koleksi.

Driver berbasis kerangka kerja dapat melakukan operasi berikut pada koleksi objek:

• Buat objek koleksi.

  Untuk membuat koleksi baru, driver dapat memanggil WdfCollectionCreate.

• Tambahkan objek ke koleksi.

  Untuk menambahkan objek ke koleksi, driver dapat memanggil WdfCollectionAdd, satu atau beberapa kali. Setiap panggilan ke WdfCollectionAdd menambahkan objek ke akhir koleksi dan menambahkan jumlah referensi objek yang ditambahkan.

• Menghapus objek dari koleksi.

  Untuk menghapus objek dari koleksi dan mengurangi jumlah referensinya, driver dapat memanggil WdfCollectionRemove atau WdfCollectionRemoveItem. Saat objek dihapus, semua objek setelah dihapus, indeksnya akan diderementasi secara otomatis.

• Mendapatkan jumlah objek dalam koleksi.

  Untuk menentukan jumlah objek yang dikandung koleksi, driver dapat memanggil WdfCollectionGetCount.

• Dapatkan handel ke objek dalam koleksi.

  Jika driver memanggil WdfCollectionGetItem, menyediakan nilai indeks sebagai argumen input, driver menerima handel ke objek yang terkait dengan nilai indeks. (Nilai indeks nol mewakili objek pertama dalam koleksi, nilai indeks satu mewakili objek kedua, dan seterusnya-seperti daftar tertaut. Ketika driver menghapus item i dari koleksi, item i+1 menjadi item i.)

  Driver juga dapat memanggil WdfCollectionGetFirstItem atau WdfCollectionGetLastItem untuk mendapatkan handel ke item pertama atau terakhir yang ditambahkan ke koleksi.

• Kunci koleksi.

  Driver dapat memanggil WdfWaitLockAcquire untuk menyinkronkan akses ke koleksi di IRQL = PASSIVE_LEVEL, atau dapat memanggil WdfSpinLockAcquire menyinkronkan akses di IRQL = DISPATCH_LEVEL. Setelah driver memperoleh kunci, koleksi tidak dapat diakses oleh kode lain di driver yang juga memanggil WdfWaitLockAcquire atau WdfSpinLockAcquire. Setelah menyelesaikan operasi pada koleksi, driver harus memanggil WdfWaitLockRelease.

  Memanggil WdfWaitLockAcquire atau WdfSpinLockAcquire tidak mencegah kode lain dalam driver mengakses koleksi secara bersamaan, jika kode lain tersebut tidak juga memanggil WdfWaitLockAcquire atau WdfSpinLockAcquire.

• Menghapus koleksi.

  Untuk menghapus objek koleksi, driver dapat memanggil WdfObjectDelete. Namun, biasanya driver menentukan objek induk saat mereka membuat koleksi, dan kerangka kerja menghapus objek koleksi saat menghapus objek induk.

  Misalnya, jika driver membuat sekumpulan objek permintaan sehingga dapat memecah permintaan I/O besar menjadi permintaan yang lebih kecil, itu dapat membuat objek permintaan I/O besar menjadi objek induk objek koleksi. Akhirnya target I/O driver akan memanggil WdfRequestComplete untuk menyelesaikan permintaan yang lebih kecil. Pada saat itu, driver dapat memanggil WdfRequestComplete untuk permintaan I/O besar, menyebabkan kerangka kerja menghapus objek permintaan dan objek turunannya: objek koleksi.

  Saat kerangka kerja menghapus objek koleksi yang berisi objek yang belum dihapus, kerangka kerja akan menghapus objek dari koleksi dan mengurangi jumlah referensinya, tetapi hanya menghapus objek koleksi.

Terkadang driver harus memeriksa semua objek dalam koleksi. Contoh kode berikut menunjukkan situasi ini:

WdfWaitLockAcquire(CollectionLockHandle, NULL);
ItemCount = WdfCollectionGetCount(CollectionHandle);
for (i=0; i<ItemCount; i++) {
    ObjectHandle = WdfCollectionGetItem(CollectionHandle, i);
    // 1. Call object-specific methods to obtain object properties.
    // 2. Perform object-specific operations.
    }
WdfWaitLockRelease(CollectionLockHandle);