Fungsi IoSetCompletionRoutine (wdm.h)

Artikel
03/08/2023

Rutinitas IoSetCompletionRoutine mendaftarkan rutinitas IoCompletion , yang akan dipanggil ketika driver tingkat bawah berikutnya telah menyelesaikan operasi yang diminta untuk IRP yang diberikan.

Sintaks

void IoSetCompletionRoutine(
  [in]           PIRP                   Irp,
  [in, optional] PIO_COMPLETION_ROUTINE CompletionRoutine,
  [in, optional] __drv_aliasesMem PVOID Context,
  [in]           BOOLEAN                InvokeOnSuccess,
  [in]           BOOLEAN                InvokeOnError,
  [in]           BOOLEAN                InvokeOnCancel
);

Parameter

[in] Irp

Arahkan ke IRP yang sedang diproses driver.

[in, optional] 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

Tidak ada

Keterangan

Hanya driver yang dapat menjaminnya tidak akan dibongkar sebelum penyelesaiannya selesai rutin dapat menggunakan IoSetCompletionRoutine. Jika tidak, driver harus menggunakan IoSetCompletionRoutineEx, yang mencegah driver membongkar hingga rutinitas penyelesaiannya dijalankan.

Rutinitas ini menetapkan alamat transfer rutinitas IoCompletion dalam IRP yang diberikan. Driver tingkat terendah dalam rantai driver berlapis tidak dapat memanggil rutinitas ini.

IoSetCompletionRoutine mendaftarkan rutinitas yang ditentukan untuk dipanggil ketika driver tingkat bawah berikutnya telah menyelesaikan operasi yang diminta dengan salah satu atau semua cara berikut:

Dengan nilai status keberhasilan
Dengan nilai status yang tidak berhasil
Dengan membatalkan IRP

Biasanya, blok status I/O diatur oleh driver perangkat yang mendasar. Ini dibaca tetapi tidak diubah oleh rutinitas IoCompletion driver tingkat lebih tinggi.

Driver tingkat lebih tinggi yang mengalokasikan IRP dengan IoAllocateIrp atau IoBuildAsynchronousFsdRequest harus memanggil rutinitas ini dengan semua parameter InvokeOnXxx yang diatur ke TRUE sebelum meneruskan IRP yang dialokasikan driver ke IoCallDriver. Ketika rutinitas IoCompletion dipanggil dengan IRP seperti itu, itu harus membebaskan IRP yang dialokasikan driver dan sumber daya lain yang disiapkan driver untuk permintaan, seperti MDL dengan IoBuildPartialMdl. Driver seperti itu harus mengembalikan STATUS_MORE_PROCESSING_REQUIRED ketika memanggil IoFreeIrp ke forestall pemrosesan penyelesaian manajer I/O untuk IRP yang dialokasikan driver.

Driver non-PnP yang mungkin dibongkar sebelum rutinitas IoCompletion mereka berjalan harus menggunakan IoSetCompletionRoutineEx sebagai gantinya.

Persyaratan

Persyaratan	Nilai
Target Platform	Desktop
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
IRQL	IRQL <= DISPATCH_LEVEL
Aturan kepatuhan DDI	CompleteRequest(wdm), CompleteRequestStatusCheck(wdm), CompletionRoutineRegistered(wdm), IoAllocateForward(wdm), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildFsdForward(wdm), IoBuildFsdIrpSignalEventInCompletion(wdm), IoBuildFsdIrpSignalEventInCompletion2(wdm), IoBuildFsdIrpSignalEventInCompletion3(wdm), IoBuildFsdIrpSignalEventInCompletionTimeout(wdm), IoFreeIrp(storport), IoSetCompletionRoutineNonPnpDriver(wdm), LowerDriverReturn(wdm), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PendedCompletedRequest(wdm), SetCompletionRoutineFromDispatch(kmdf), SignalEventInCompletion(wdm), SignalEventInCompletion2(wdm), SignalEventInCompletion3(wdm), StartDeviceWait(wdm), StartDeviceWait3(wdm)