Fungsi IoSetCompletionRoutineEx (wdm.h)
Rutinitas IoSetCompletionRoutineEx mendaftarkan rutinitas IoCompletion , yang dipanggil ketika driver tingkat bawah berikutnya telah menyelesaikan operasi yang diminta untuk IRP yang diberikan.
Sintaks
NTSTATUS IoSetCompletionRoutineEx(
[in] PDEVICE_OBJECT DeviceObject,
[in] PIRP Irp,
[in] PIO_COMPLETION_ROUTINE CompletionRoutine,
[in, optional] PVOID Context,
[in] BOOLEAN InvokeOnSuccess,
[in] BOOLEAN InvokeOnError,
[in] BOOLEAN InvokeOnCancel
);
Parameter
[in] DeviceObject
Arahkan ke objek perangkat driver.
[in] Irp
Arahkan ke IRP yang sedang diproses driver.
[in] CompletionRoutine
Menentukan titik masuk untuk rutinitas IoCompletion yang disediakan driver, yang dipanggil ketika driver berikutnya yang lebih rendah menyelesaikan paket.
[in, optional] Context
Arahkan ke konteks yang ditentukan driver untuk diteruskan ke rutinitas IoCompletion . Informasi konteks harus disimpan dalam memori yang tidak dipagasi, karena rutinitas IoCompletion dipanggil di IRQL <= DISPATCH_LEVEL.
[in] InvokeOnSuccess
Menentukan apakah rutinitas penyelesaian dipanggil jika IRP diselesaikan dengan nilai status keberhasilan dalam struktur IO_STATUS_BLOCK IRP, berdasarkan hasil makro NT_SUCCESS (lihat Menggunakan nilai NTSTATUS).
[in] InvokeOnError
Menentukan apakah rutinitas penyelesaian dipanggil jika IRP diselesaikan dengan nilai status tidak berhasil dalam struktur IO_STATUS_BLOCK IRP.
[in] InvokeOnCancel
Menentukan apakah rutinitas penyelesaian dipanggil jika driver atau kernel telah memanggil IoCancelIrp untuk membatalkan IRP.
Nilai kembali
Rutinitas ini mengembalikan STATUS_SUCCESS pada keberhasilan, atau STATUS_INSUFFICIENT_RESOURCES jika memori yang tidak memadai tersedia untuk operasi.
Keterangan
Tidak seperti IoSetCompletionRoutine, rutinitas IoSetCompletionRoutineEx mengembalikan nilai NTSTATUS. Driver harus memeriksa nilai ini untuk menentukan apakah rutinitas IoCompletion berhasil didaftarkan. Jika rutinitas IoCompletion berhasil didaftarkan, IoSetCompletionRoutineEx mengalokasikan memori yang tetap dialokasikan hingga rutinitas IoCompletion dijalankan. Driver harus memastikan bahwa rutinitas IoCompletion mereka dijalankan dengan memanggil IoCallDriver; jika tidak, kernel akan membocorkan memori.
Rutinitas IoCompletion harus milik driver yang memiliki objek perangkat yang diacu oleh DeviceObject. Persyaratan ini mencegah rutinitas IoCompletion dibongkar sebelum dikembalikan.
Perilaku IoSetCompletionRoutineEx sama dengan rutinitas IoSetCompletionRoutine , kecuali bahwa:
IoSetCompletionRoutineEx menjamin bahwa driver non-Plug and Play tidak dibongkar sebelum rutinitas IoCompletion berjalan.
IoSetCompletionRoutineEx adalah rutinitas yang mengembalikan nilai NTSTATUS.