Fungsi IoSetCompletionRoutineEx (wdm.h)

Artikel
03/08/2023

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.

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Aturan kepatuhan DDI	CompleteRequest(wdm), CompleteRequestStatusCheck(wdm), CompletionRoutineRegistered(wdm), HwStorPortProhibitedDIs(storport), IoAllocateForward(wdm), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildFsdForward(wdm), IoBuildFsdIrpSignalEventInCompletion(wdm), IoBuildFsdIrpSignalEventInCompletion2(wdm), IoBuildFsdIrpSignalEventInCompletion3(wdm), IoBuildFsdIrpSignalEventInCompletionTimeout(wdm), IoSetCompletionExCompleteIrp(wdm), IoSetCompletionRoutineExCheck(wdm), IoSetCompletionRoutineExCheckDeviceObject(wdm), LowerDriverReturn(wdm), MarkPower(wdm), MarkPowerDown(wdm) , MarkQueryRelations(wdm), MarkStartDevice(wdm), PendedCompletedRequestEx(wdm), SetCompletionRoutineFromDispatch(kmdf), SignalEventInCompletion(wdm), SignalEventInCompletion2(wdm), SignalEventInCompletion3(wdm), StartDeviceWait2(wdm), StartDeviceWait4(wdm)