Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
IoCompletion rutin menyelesaikan pemrosesan operasi I/O.
Sintaksis
IO_COMPLETION_ROUTINE IoCompletionRoutine;
NTSTATUS IoCompletionRoutine(
[in] PDEVICE_OBJECT DeviceObject,
[in] PIRP Irp,
[in, optional] PVOID Context
)
{...}
Parameter
[in] DeviceObject
Penunjuk yang disediakan penelepon ke struktur DEVICE_OBJECT. Ini adalah objek perangkat untuk perangkat target, yang sebelumnya dibuat oleh rutinitas AddDevice driver.
[in] Irp
Penunjuk yang disediakan penelepon ke struktur IRP yang menjelaskan operasi I/O.
[in, optional] Context
Penunjuk yang disediakan pemanggil ke informasi konteks khusus driver, sebelumnya disediakan saat memanggil IoSetCompletionRoutine atau IoSetCompletionRoutineEx. Informasi konteks harus disimpan dalam memori yang tidak disebarkan, karena IoCompletion rutin dapat dipanggil pada DISPATCH_LEVEL. Untuk informasi selengkapnya, lihat bagian Komentar berikut ini.
Mengembalikan nilai
Jika IoCompletion rutin menentukan bahwa pemrosesan tambahan diperlukan untuk IRP, itu harus mengembalikan STATUS_MORE_PROCESSING_REQUIRED. Untuk informasi selengkapnya, lihat bagian Komentar berikut ini. Jika tidak, itu harus mengembalikan STATUS_SUCCESS. (Manajer I/O hanya memeriksa keberadaan atau tidak adanya STATUS_MORE_PROCESSING_REQUIRED.)
Komentar
Rutinitas IoCompletion driver dijalankan dalam rangkaian arbitrer atau DPC, dan pada IRQL yang kurang dari atau sama dengan DISPATCH_LEVEL. Karena kode yang ditulis untuk dijalankan pada DISPATCH_LEVEL juga akan dijalankan pada tingkat yang lebih rendah, rutinitas IoCompletion harus dirancang untuk eksekusi pada DISPATCH_LEVEL. Namun, karena rutinitas ini tidak dijamin berjalan pada DISPATCH_LEVEL, mereka tidak boleh memanggil rutinitas sistem yang benar-benar memerlukan eksekusi pada DISPATCH_LEVEL. (Untuk informasi selengkapnya tentang IRQL, lihat Mengelola Prioritas Perangkat Keras.)
Untuk mendaftarkan rutinitas IoCompletion untuk IRP tertentu, driver harus memanggil IoSetCompletionRoutine atau IoSetCompletionRoutineEx, yang menyimpan alamat rutin IoCompletion di lokasi tumpukan I/O driver yang lebih rendah berikutnya. (Dengan demikian, driver tingkat terendah tidak dapat mendaftarkan IoCompletion rutin.) Driver biasanya memanggil IoSetCompletionRoutine atau IoSetCompletionRoutineEx dari salah satu rutinitas pengirimannya, setiap kali IRP diterima. Sebagian besar driver, termasuk semua driver PnP, dapat menggunakan IoSetCompletionRoutine untuk mendaftarkan IoCompletion rutin mereka. Driver non-PnP yang dapat dibongkar sebelum IoCompletion rutin dijalankan harus menggunakan IoSetCompletionRoutineEx sebagai gantinya.
Ketika setiap driver menyelesaikan IRP, driver memanggil IoCompleteRequest, yang pada gilirannya memanggil IoCompletion rutin setiap driver tingkat lebih tinggi, dari yang tertinggi berikutnya ke tertinggi, sampai semua IoCompletion rutinitas yang lebih tinggi telah dipanggil atau sampai satu rutinitas kembali STATUS_MORE_PROCESSING_REQUIRED.
Saat Anda membuat IRP, alokasikan lokasi tumpukan untuk driver saat ini serta driver yang lebih rendah. Jika Anda tidak mengalokasikan lokasi tumpukan yang memadai, penunjuk DeviceObject mungkin diatur ke NULL ketika rutinitas penyelesaian dipanggil. Anda dapat menghindari alokasi lokasi tumpukan tambahan untuk driver saat ini jika Anda menggunakan bidang Konteks untuk meneruskan informasi ke IoCompletion daripada mengandalkan parameter DeviceObject.
Jika rutinitas IoCompletion mengembalikan STATUS_MORE_PROCESSING_REQUIRED, panggilan driver yang lebih rendah untuk IoCompleteRequest segera kembali. Dalam hal ini, driver tingkat yang lebih tinggi harus memanggil IoCompleteRequest untuk menyelesaikan IRP.
Untuk informasi selengkapnya tentang menerapkan rutinitas IoCompletion, lihat Menyelesaikan runtime integrasi.
Contoh
Untuk menentukan rutinitas panggilan balik IoCompletion, Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis rutinitas panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk pengandar. Mendeklarasikan fungsi menggunakan jenis fungsi panggilan balik membantu Analisis Kode untuk Driver, Pemverifikasi Driver Statis (SDV), dan alat verifikasi lainnya menemukan kesalahan, dan itu adalah persyaratan untuk menulis driver untuk sistem operasi Windows.
Misalnya, untuk menentukan rutinitas panggilan balik IoCompletion yang diberi nama MyIoCompletion
, gunakan jenis IO_COMPLETION_ROUTINE seperti yang ditunjukkan dalam contoh kode ini:
IO_COMPLETION_ROUTINE MyIoCompletion;
Kemudian, terapkan rutinitas panggilan balik Anda sebagai berikut:
_Use_decl_annotations_
NTSTATUS
MyIoCompletion(
PDEVICE_OBJECT DeviceObject,
PIRP Irp,
PVOID Context
)
{
// Function body
}
Jenis fungsi IO_COMPLETION_ROUTINE ditentukan dalam file header Wdm.h. Untuk mengidentifikasi kesalahan dengan lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan anotasi _Use_decl_annotations_
ke definisi fungsi Anda. Anotasi _Use_decl_annotations_
memastikan bahwa anotasi yang diterapkan ke jenis fungsi IO_COMPLETION_ROUTINE dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver WDM. Untuk informasi tentang _Use_decl_annotations_
, lihat Anotasi Perilaku Fungsi.
Persyaratan
Syarat | Nilai |
---|---|
Platform Target | Desktop |
Header | wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h) |
IRQL | Dipanggil di IRQL <= DISPATCH_LEVEL (lihat bagian Keterangan). |