PFLT_INSTANCE_TEARDOWN_CALLBACK fungsi panggilan balik (fltkernel.h)

Artikel
02/26/2024

Driver minifilter dapat mendaftarkan dua rutinitas jenis PFLT_INSTANCE_TEARDOWN_CALLBACK sebagai rutinitas InstanceTeardownStartCallback dan InstanceTeardownCompleteCallback driver minifilter.

Sintaks

PFLT_INSTANCE_TEARDOWN_CALLBACK PfltInstanceTeardownCallback;

void PfltInstanceTeardownCallback(
  [in] PCFLT_RELATED_OBJECTS FltObjects,
  [in] FLT_INSTANCE_TEARDOWN_FLAGS Reason
)
{...}

Parameter

[in] FltObjects

Penunjuk ke struktur FLT_RELATED_OBJECTS yang berisi pointer buram untuk objek yang terkait dengan operasi I/O saat ini.

[in] Reason

Bendera yang menunjukkan mengapa instans driver minifilter sedang dirobohkan. Salah satu dari berikut ini:

Bendera	Makna
FLTFL_INSTANCE_TEARDOWN_MANUAL (0x00000001)	Instans sedang dicopot karena aplikasi mode pengguna telah disebut FilterDetach atau komponen mode kernel telah disebut FltDetachVolume.
FLTFL_INSTANCE_TEARDOWN_FILTER_UNLOAD (0x00000002)	Driver minifilter sedang dibongkar.
FLTFL_INSTANCE_TEARDOWN_MANDATORY_FILTER_UNLOAD (0x00000004)	Driver minifilter sedang dibongkar.
FLTFL_INSTANCE_TEARDOWN_VOLUME_DISMOUNT (0x00000008)	Jika diatur, volume sedang dilepas. (Atau volume telah dilepas. Atau operasi pemasangan volume gagal. Atau instans driver minifilter atau volume sedang dirobohkan. Atau sistem file tidak terdaftar sendiri sebagai sistem file aktif.)
FLTFL_INSTANCE_TEARDOWN_INTERNAL_ERROR (0x00000010)	Sistem mengalami kesalahan internal yang tidak terduga.

Mengembalikan nilai

Tidak ada

Keterangan

Ketika driver minifilter mendaftarkan dirinya dengan memanggil FltRegisterFilter dari rutinitas DriverEntry-nya , ia dapat mendaftarkan dua rutinitas jenis PFLT_INSTANCE_TEARDOWN_CALLBACK sebagai rutinitas InstanceTeardownStartCallback dan InstanceTeardownCompleteCallback driver minifilter. Untuk mendaftarkan rutinitas panggilan balik ini, driver minifilter menyimpan alamat dua rutinitas jenis PFLT_INSTANCE_TEARDOWN_CALLBACK di anggota InstanceTeardownStartCallback dan InstanceTeardownCompleteCallback dari struktur FLT_REGISTRATION yang dilewati driver minifilter sebagai parameter PendaftaranFltRegisterFilter.

Rutinitas InstanceTeardownStartCallback dan InstanceTeardownCompleteCallback bersifat opsional dan dapat berupa NULL. Jika driver minifilter menentukan NULL untuk rutinitas InstanceTeardownStartCallback atau InstanceTeardownCompleteCallback , instans masih dirobohkan.

Rutinitas InstanceTeardownStartCallback dipanggil ketika manajer filter mulai merobek instans driver minifilter untuk memungkinkan driver minifilter menyelesaikan operasi I/O yang tertunda dan menyimpan informasi status.

Rutinitas InstanceTeardownStartCallback harus:

Panggil FltCompletePendedPreOperation untuk setiap operasi I/O yang tertunda dalam rutinitas panggilan balik praoperasi driver minifilter untuk menyelesaikan operasi atau mengembalikan kontrol operasi ke manajer filter.
Operasi I/O baru tidak tertunda. Jika driver minifilter menggunakan antrean data panggilan balik, driver harus memanggil FltCbdqDisable untuk menonaktifkannya.
Panggil FltCompletePendedPostOperation untuk setiap operasi I/O yang tertunda dalam rutinitas panggilan balik pascaoperasi driver minifilter untuk mengembalikan kontrol operasi ke manajer filter.

Rutinitas InstanceTeardownStartCallback secara opsional dapat melakukan hal berikut untuk memungkinkan driver minifilter membongkar secepat mungkin:

Tutup file yang dibuka.
Pastikan bahwa utas pekerja hanya melakukan minimum yang diperlukan untuk menyelesaikan pemrosesan item kerja yang luar biasa.
Hubungi FltCancelIo untuk membatalkan operasi I/O apa pun yang dimulai oleh driver minifilter.
Berhenti mengantre item kerja baru.

Setelah rutinitas InstanceTeardownStartCallback driver minifilter dipanggil, rutinitas panggilan balik driver minifilter dan pascaoperasi tidak dipanggil untuk operasi I/O baru. Namun, mereka dapat dipanggil untuk operasi I/O yang dimulai sebelum teardown instans dimulai.

Rutinitas InstanceTeardownCompleteCallback dipanggil ketika proses teardown selesai untuk memungkinkan driver minifilter menutup file yang terbuka dan melakukan pemrosesan pembersihan lain yang diperlukan.

Rutinitas InstanceTeardownCompleteCallback harus menutup file apa pun yang dibuka oleh driver minifilter.

Manajer filter memanggil rutinitas InstanceTeardownCompleteCallback driver minifilter hanya setelah semua operasi I/O yang luar biasa telah selesai atau dikosongkan.

Peringatan

Rutinitas InstanceTeardownCompleteCallback tidak akan dipanggil jika salah satu kondisi berikut ini benar:

Ada operasi I/O tertunda yang luar biasa.
Ada operasi I/O luar biasa yang dimulai oleh driver minifilter.

Jika instans driver minifilter sedang ditumbangkan karena driver minifilter sedang dibongkar, operasi bongkar tampaknya macet sampai rutinitas InstanceTeardownCompleteCallback kembali. Untuk men-debug masalah semacam ini, Anda harus mengaktifkan Driver Verifier pada driver minifilter Anda. Opsi Verifikasi Filter Verifier I/O dapat membantu mengidentifikasi kemungkinan penyebab, seperti referensi yang belum dilepaskan, yang akan mencegah driver minifilter membongkar. Untuk informasi selengkapnya, lihat Pemverifikasi Filter.

Perhatikan bahwa mereferensikan instans (dengan memanggil FltObjectReference) tidak mencegah rutinitas InstanceTeardownCompleteCallback dipanggil.

Manajer filter memanggil rutinitas InstanceTeardownStartCallback dan InstanceTeardownCompleteCallback di IRQL PASSIVE_LEVEL.