Fungsi FltPerformAsynchronousIo (fltkernel.h)

Artikel
02/26/2024

Driver minifilter memanggil FltPerformAsynchronousIo untuk memulai operasi I/O asinkron.

Sintaks

NTSTATUS FLTAPI FltPerformAsynchronousIo(
  [in, out] PFLT_CALLBACK_DATA               CallbackData,
  [in]      PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
  [in]      PVOID                            CallbackContext
);

Parameter

[in, out] CallbackData

Arahkan ke struktur data panggilan balik (FLT_CALLBACK_DATA) yang dialokasikan oleh panggilan sebelumnya ke FltAllocateCallbackData. Parameter ini diperlukan dan tidak boleh NULL. Pemanggil bertanggung jawab untuk membebaskan struktur ini ketika tidak lagi diperlukan dengan memanggil FltFreeCallbackData.

[in] CallbackRoutine

Penunjuk ke rutinitas panggilan balik PFLT_COMPLETED_ASYNC_IO_CALLBACK-ketik untuk dipanggil ketika operasi I/O selesai. Catatan: Manajer Filter memanggil rutinitas ini setelah memanggil rutinitas panggilan balik pascaoperasi (PFLT_POST_OPERATION_CALLBACK) dari setiap driver minifilter yang instansnya dilampirkan di bawah instans yang memulai (ditentukan dalam parameter Instans ke FltAllocateCallbackData). Parameter ini diperlukan dan tidak boleh NULL. Filter Manager selalu memanggil rutinitas ini, bahkan ketika FltPerformAsynchronousIo gagal.

[in] CallbackContext

Penunjuk konteks yang akan diteruskan ke CallbackRoutine Parameter ini bersifat opsional dan dapat berupa NULL.

Nilai kembali

FltPerformAsynchronousIo mengembalikan STATUS_SUCCESS untuk menunjukkan bahwa operasi I/O diselesaikan oleh sistem file, dan rutinitas panggilan balik yang ditunjuk oleh CallbackRoutine telah dipanggil. Jika tidak, ia mengembalikan nilai NTSTATUS yang sesuai seperti salah satu hal berikut ini:

Menampilkan kode	Deskripsi
STATUS_FLT_INVALID_ASYNCHRONOUS_REQUEST	IRP_MJ_CREATE permintaan tidak dapat dilakukan secara asinkron. Ini adalah kode kesalahan.
STATUS_PENDING	Operasi mengembalikan STATUS_PENDING. Filter Manager akan memanggil rutinitas panggilan balik yang ditunjuk callbackRoutine saat operasi I/O selesai. Kode ini hanya menunjukkan bahwa operasi dimulai.
STATUS_FLT_IO_COMPLETE	Operasi diselesaikan dengan rutinitas panggilan balik praoperasi driver minifilter yang instansnya dilampirkan di bawah instans yang memulai.

Keterangan

Driver minifilter memanggil FltPerformAsynchronousIo untuk memulai operasi I/O asinkron setelah memanggil FltAllocateCallbackData untuk mengalokasikan struktur data panggilan balik untuk operasi.

FltPerformAsynchronousIo mengirimkan operasi I/O hanya ke instans driver minifilter yang terpasang di bawah instans yang memulai (ditentukan dalam parameter Instans ke FltAllocateCallbackData), dan sistem file. Driver minifilter yang terpasang di atas instans yang ditentukan tidak menerima operasi I/O.

Driver minifilter hanya dapat memulai operasi I/O berbasis IRP. Mereka tidak dapat memulai operasi panggilan balik I/O atau filter sistem file (FSFilter) yang cepat.

Driver minifilter harus menggunakan FltPerformAsynchronousIo hanya untuk operasi I/O asinkron yang rutinitasnya seperti berikut ini tidak dapat digunakan:

IRP_MJ_CREATE permintaan tidak dapat dilakukan secara asinkron.

Struktur data panggilan balik (FLT_CALLBACK_DATA) dapat dibebaskan atau digunakan kembali kapan saja setelah rutinitas panggilan balik yang dipanggil oleh CallbackRoutine . Pemanggil dapat membebaskan struktur data panggilan balik dengan memanggil FltFreeCallbackData atau menyiapkannya untuk digunakan kembali dengan memanggil FltReuseCallbackData.

Catatan

STATUS_SUCCESS dan STATUS_FLT_IO_COMPLETE menunjukkan bahwa operasi I/O selesai, tetapi tidak menunjukkan status akhir operasi I/O. Untuk menentukan status operasi aktual yang dikembalikan oleh driver minifilter, driver filter, dan sistem file yang mendasar, CallbackRoutine harus memeriksa anggota IoStatus dari struktur data panggilan balik yang diterima dalam parameter CallbackContextCallbackRoutine.

Karena Filter Manager selalu memanggil rutinitas panggilan balik yang ditunjuk callbackRoutine , bahkan ketika FltPerformAsynchronousIo gagal, driver minifilter dapat melakukan operasi membebaskan atau menggunakan kembali langsung dalam rutinitas panggilan balik.

Pemanggil FltPerformAsynchronousIo dapat berjalan di IRQL <= APC_LEVEL jika bendera IRP_PAGING_IO diatur dalam anggota IrpFlags dari struktur FLT_IO_PARAMETER_BLOCK untuk operasi. (Bendera ini hanya berlaku untuk operasi IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_QUERY_INFORMATION, dan IRP_MJ_SET_INFORMATION.) Jika tidak, penelepon harus berjalan di IRQL PASSIVE_LEVEL.