Menyelesaikan Permintaan I/O

Setiap driver berbasis kerangka kerja pada akhirnya harus menyelesaikan setiap permintaan I/O yang diterimanya dari kerangka kerja. Driver menyelesaikan permintaan dengan memanggil metode WdfRequestComplete, WdfRequestCompleteWithInformation, atau WdfRequestCompleteWithPriorityBoost objek permintaan.

Kapan Harus Menyelesaikan Permintaan

Driver harus menyelesaikan permintaan ketika menentukan bahwa salah satu kasus berikut ini benar:

• Operasi I/O yang diminta telah berhasil diselesaikan.

• Operasi I/O yang diminta dimulai tetapi gagal sebelum selesai.

• Operasi I/O yang diminta tidak didukung, atau tidak valid pada saat diterima, dan tidak dapat dimulai.

• Operasi I/O yang diminta dibatalkan.

Jika driver melayani permintaan I/O dengan membuat aktivitas I/O pada perangkat, driver biasanya memanggil WdfRequestComplete dari fungsi panggilan balik EvtInterruptDpc atau EvtDpcFunc .

Jika driver menerima permintaan yang tidak didukung atau tidak valid, biasanya memanggil WdfRequestComplete dari penangan permintaan yang menerima permintaan.

Jika operasi I/O dibatalkan, driver biasanya memanggil WdfRequestComplete dari fungsi panggilan balik EvtRequestCancel-nya .

Jika driver meneruskan permintaan I/O ke target I/O, driver menyelesaikan permintaan setelah target I/O menyelesaikan permintaan, sebagai berikut:

• Jika driver Anda meneruskan permintaan I/O secara sinkron ke target I/O, panggilan driver ke target I/O hanya kembali setelah driver tingkat bawah menyelesaikan permintaan (kecuali terjadi kesalahan). Setelah target I/O kembali, driver Anda harus memanggil WdfRequestComplete.

• Jika driver Anda meneruskan permintaan I/O secara asinkron, Anda akan ingin driver Anda diberi tahu ketika driver tingkat bawah menyelesaikan permintaan. Jika driver Anda mendaftarkan fungsi panggilan balik CompletionRoutine , kerangka kerja memanggil fungsi panggilan balik ini setelah target I/O menyelesaikan permintaan. Fungsi panggilan balik CompletionRoutine biasanya memanggil WdfRequestComplete.

Untuk mendaftarkan fungsi panggilan balik CompletionRoutine , driver harus memanggil WdfRequestSetCompletionRoutine sebelum meneruskan permintaan I/O ke target I/O.

Jika driver Anda tidak perlu diberi tahu ketika target I/O menyelesaikan permintaan I/O yang diteruskan secara asinkron, driver tidak perlu mendaftarkan fungsi panggilan balik CompletionRoutine . Sebagai gantinya, driver dapat mengatur bendera WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET saat memanggil WdfRequestSend. Dalam hal ini driver tidak memanggil WdfRequestComplete.

Driver tidak menyelesaikan permintaan I/O yang telah dibuat dengan memanggil WdfRequestCreate atau WdfRequestCreateFromIrp. Sebagai gantinya, driver harus memanggil WdfObjectDelete untuk menghapus objek permintaan, biasanya setelah target I/O menyelesaikan permintaan.

Misalnya, driver mungkin menerima permintaan baca atau tulis untuk sejumlah data yang lebih besar dari yang dapat ditangani oleh target I/O driver pada satu waktu. Driver harus membagi data menjadi beberapa permintaan yang lebih kecil dan mengirim permintaan yang lebih kecil ini ke satu atau beberapa target I/O. Teknik untuk menangani situasi ini meliputi:

• Memanggil WdfRequestCreate untuk membuat satu objek permintaan tambahan yang mewakili permintaan yang lebih kecil.

  Driver dapat mengirim permintaan ini secara sinkron ke target I/O. Fungsi panggilan balik CompletionRoutine permintaan yang lebih kecil dapat memanggil WdfRequestReuse sehingga driver dapat menggunakan kembali permintaan dan mengirimkannya ke target I/O lagi. Setelah target I/O menyelesaikan permintaan terakhir yang lebih kecil, fungsi panggilan balik CompletionRoutine dapat memanggil WdfObjectDelete untuk menghapus objek permintaan yang dibuat driver dan driver dapat memanggil WdfRequestComplete untuk menyelesaikan permintaan asli.

• Memanggil WdfRequestCreate untuk membuat beberapa objek permintaan tambahan yang mewakili permintaan yang lebih kecil.

  Target I/O driver dapat memproses beberapa permintaan yang lebih kecil ini secara asinkron. Driver dapat mendaftarkan fungsi panggilan balik CompletionRoutine untuk setiap permintaan yang lebih kecil. Setiap kali fungsi panggilan balik CompletionRoutine dipanggil, fungsi ini dapat memanggil WdfObjectDelete untuk menghapus objek permintaan yang dibuat driver. Setelah target I/O menyelesaikan semua permintaan yang lebih kecil, driver dapat memanggil WdfRequestComplete untuk menyelesaikan permintaan asli.

Memberikan Informasi Penyelesaian

Ketika driver menyelesaikan permintaan, driver dapat secara opsional memberikan beberapa informasi tambahan yang dapat diakses driver lain. Misalnya, driver mungkin memberikan jumlah byte yang ditransfer untuk permintaan baca atau tulis. Untuk memberikan informasi ini, driver dapat melakukan salah satu hal berikut:

• Panggil WdfRequestSetInformation sebelum memanggil WdfRequestComplete.

• Panggil WdfRequestCompleteWithInformation.

Mendapatkan Informasi Penyelesaian

Untuk mendapatkan informasi tentang permintaan I/O yang telah diselesaikan driver lain, driver dapat:

• Panggil WdfRequestGetStatus untuk mendapatkan nilai status penyelesaian yang ditentukan driver tingkat bawah saat disebut WdfRequestComplete.

• Panggil WdfRequestGetCompletionParams untuk mendapatkan struktur WDF_REQUEST_COMPLETION_PARAMS yang berisi informasi tambahan tentang permintaan yang telah selesai, seperti menangani objek memori yang mewakili buffer permintaan, atau informasi khusus bus.

  Driver dapat memanggil WdfRequestGetCompletionParams hanya setelah memanggil WdfRequestSend untuk mengirim permintaan I/O secara sinkron atau asinkron ke target I/O. Driver tidak boleh memanggil WdfRequestGetCompletionParams setelah memanggil salah satu metode yang mengirim permintaan I/O ke target I/O hanya secara sinkron (seperti WdfIoTargetSendReadSynchronously).

• Panggil WdfRequestGetInformation untuk mendapatkan informasi penyelesaian I/O tambahan yang ditentukan driver tingkat bawah ketika disebut WdfRequestSetInformation atau WdfRequestCompleteWithInformation, jika driver dalam tumpukan driver memberikan informasi tersebut.

Jika driver mengirim permintaan I/O secara sinkron, biasanya memanggil WdfRequestGetStatus, WdfRequestGetCompletionParams, dan WdfRequestGetInformation setelah panggilan sinkron kembali. Jika driver mengirim permintaan I/O secara asinkron, biasanya memanggil metode ini dari dalam fungsi panggilan balik CompletionRoutine .

Untuk informasi selengkapnya tentang menyelesaikan permintaan I/O, lihat Menyinkronkan Kode Pembatalan dan Penyelesaian.