Fungsi FltQueryDirectoryFileEx (fltkernel.h)

Artikel
07/16/2024

FltQueryDirectoryFileEx mengembalikan berbagai jenis informasi tentang file dalam direktori yang ditentukan oleh objek file tertentu.

Sintaksis

NTSTATUS FLTAPI FltQueryDirectoryFileEx(
  PFLT_INSTANCE          Instance,
  PFILE_OBJECT           FileObject,
  PVOID                  FileInformation,
  ULONG                  Length,
  FILE_INFORMATION_CLASS FileInformationClass,
  ULONG                  QueryFlags,
  PUNICODE_STRING        FileName,
  PULONG                 LengthReturned
);

Parameter

Instance

Pointer buram ke instans driver minifilter yang memulai I/O ini.

FileObject

Penunjuk ke objek file yang mewakili direktori yang sedang dikueri.

FileInformation

Penunjuk ke buffer yang menerima informasi yang diinginkan tentang file. Struktur informasi yang dikembalikan dalam buffer ditentukan oleh parameter FileInformationClass.

Length

Ukuran, dalam byte, dari buffer yang ditunjukkan oleh FileInformation. Pemanggil harus mengatur parameter ini sesuai dengan FileInformationClass yang diberikan.

FileInformationClass

Jenis informasi yang akan dikembalikan tentang file dalam direktori. Lihat parameter FileInformationClassNtQueryDirectoryFileEx untuk daftar nilai yang mungkin.

QueryFlags

Satu atau beberapa bendera yang terkandung dalam SL_QUERY_DIRECTORY_MASK. Nilai yang mungkin ditentukan dalam tabel berikut.

Nilai	Arti
SL_RESTART_SCAN (0x00000001)	Jika bendera ini diatur, pemindaian akan dimulai pada entri pertama di direktori. Jika bendera ini tidak diatur, pemindaian akan dilanjutkan dari tempat kueri terakhir berakhir.
SL_RETURN_SINGLE_ENTRY (0x00000002)	Biasanya buffer pengembalian dikemas dengan entri direktori yang cocok sebanyak yang cocok. Jika bendera ini diatur, sistem file hanya akan mengembalikan satu entri direktori pada satu waktu. Ini memang membuat operasi kurang efisien.
SL_INDEX_SPECIFIED (0x00000004)	Jika bendera ini diatur, pemindaian harus dimulai pada posisi terindeks tertentu di direktori. Bendera ini hanya dapat diatur jika Anda membuatIRP IRP_MJ_DIRECTORY_CONTROL Anda sendiri; indeks ditentukan dalam IRP. Bagaimana posisi ditentukan bervariasi dari sistem file ke sistem file.
SL_RETURN_ON_DISK_ENTRIES_ONLY (0x00000008)	Jika bendera ini diatur, setiap filter sistem file yang melakukan virtualisasi direktori atau ekspansi just-in-time hanya boleh meneruskan permintaan ke sistem file dan mengembalikan entri yang saat ini ada di disk. Tidak semua sistem file mendukung bendera ini.
SL_NO_CURSOR_UPDATE_QUERY (0x00000010)	Sistem file mempertahankan informasi kursor direktori FileObject. Ketika beberapa utas melakukan kueri menggunakan fileObjectyang sama, akses ke struktur FileObject peradalah utas tunggal untuk mencegah kerusakan status kursor. Bendera ini memberi tahu sistem file untuk tidak memperbarui per-FileObject informasi status kursor sehingga memungkinkan beberapa utas untuk mengkueri secara paralel menggunakan handel yang sama. Ini bersifat seolah-olah SL_RESTART_SCAN ditentukan pada setiap panggilan. Jika pola kartubebas diberikan pada panggilan berikutnya, operasi tidak akan mengambil tempat kueri terakhir berakhir. Ini memungkinkan dukungan kueri direktori asinkron yang sebenarnya. Jika bendera ini digunakan di dalam transaksi TxF, operasi akan gagal. Tidak semua sistem file mendukung bendera ini.

FileName

Penunjuk ke struktur UNICODE_STRING yang dialokasikan pemanggil dengan string Unicode yang berisi nama file (atau beberapa file, jika wildcard digunakan) dalam direktori yang ditentukan oleh FileObject. Parameter ini bersifat opsional dan dapat NULL. Jika fileNameNULL , semua file disertakan.

Jika FileName tidak NULL, hanya file yang namanya cocok dengan string FileName yang disertakan dalam pemindaian direktori. Jika bendera QueryFlagsResetScan diatur, nilai FileName diabaikan.

LengthReturned

Menerima jumlah byte yang benar-benar ditulis ke buffer FileInformation yang diberikan.

Mengembalikan nilai

FltQueryDirectoryFileEx mengembalikan STATUS_SUCCESS atau kode kesalahan yang sesuai. Kumpulan nilai status kesalahan yang dapat dikembalikan adalah file khusus sistem.

Komentar

FltQueryDirectoryFileEx mengembalikan informasi tentang file yang terkandung dalam direktori yang diwakili oleh FileObject.

Panggilan pertama ke FltQueryDirectoryFileEx menentukan serangkaian entri yang akan disertakan dalam pemindaian direktori untuk semua panggilan berikutnya, berdasarkan nilai QueryFlags dan FileName. Jika ada setidaknya satu entri yang cocok, FltQueryDirectoryFileEx membuat struktur_INFORMATION XXX FILE_(lihat tabel di atas) untuk setiap entri secara bergantian dan menyimpan struktur dalam buffer.

Dengan asumsi bahwa setidaknya satu entri direktori yang cocok ditemukan, jumlah entri yang informasinya dikembalikan adalah yang terkecil dari yang berikut ini:

Satu entri, jika bendera SL_RETURN_SINGLE_ENTRY diatur dalam QueryFlags dan FileNameNULL.
Jumlah entri yang cocok dengan string FileName, jika FileName tidak NULL. (Perhatikan bahwa jika string tidak berisi kartubebas, paling banyak ada satu entri yang cocok.)
Jumlah entri yang informasinya cocok dalam buffer yang ditunjukkan oleh FileInformation.
Jumlah entri yang terkandung dalam direktori.

Pada panggilan pertama ke FltQueryDirectoryFileEx, jika struktur yang dibuat untuk entri pertama yang ditemukan terlalu besar untuk dimasukkan ke dalam buffer output, hanya bagian tetap dari struktur yang dikembalikan. Bagian tetap terdiri dari semua bidang struktur kecuali string FileName akhir. Subsistem I/O memastikan bahwa buffer cukup besar untuk menahan bagian tetap dari struktur_INFORMATION FILE_XXX yang sesuai (hanya pada panggilan pertama dan bukan pada panggilan berikutnya). Ketika ini terjadi, FltQueryDirectoryFileEx mengembalikan nilai status STATUS_BUFFER_OVERFLOW. Juga pada panggilan pertama ke FltQueryDirectoryFileEx, jika tidak ada file di direktori FileObject yang cocok dengan parameter FileName, FltQueryDirectoryFileEx mengembalikan STATUS_NO_SUCH_FILE.

Pada setiap panggilan, FltQueryDirectoryFileEx mengembalikan struktur_INFORMATION XXX FILE_(satu per entri direktori) seperti yang dapat dimuat sepenuhnya dalam buffer yang diarahkan oleh FileInformation. Selama buffer output berisi setidaknya satu struktur lengkap, nilai status yang dikembalikan STATUS_SUCCESS. Tidak ada informasi tentang entri yang tersisa yang dilaporkan. Dengan demikian, kecuali dalam kasus yang tercantum di atas di mana hanya satu entri yang dikembalikan, FltQueryDirectoryFileEx harus dipanggil setidaknya dua kali untuk menghitung konten seluruh direktori (misalnya, ketika parameter FileName berisi satu atau beberapa karakter wildcard atau NULL).

Panggilan terakhir ke FltQueryDirectoryFileEx mengembalikan buffer output kosong dan melaporkan nilai status non-kesalahan STATUS_NO_MORE_FILES.

Catatan: Ketika FltQueryDirectoryFileEx dipanggil beberapa kali pada direktori yang sama, ada kemungkinan bahwa jumlah entri yang informasinya dikembalikan akan kurang dari yang diharapkan. Ini karena serangkaian entri yang akan disertakan dalam pemindaian direktori diperbaiki pada panggilan pertama ke FltQueryDirectoryFileEx. Dalam panggilan berikutnya, FltQueryDirectoryFileEx melanjutkan pemindaian direktori di mana pun ia meninggalkan dalam enumerasi yang sama ini. Namun, antara panggilan ke FltQueryDirectoryFileEx, entri direktori aktual dapat berubah sehingga tidak lagi sinkron dengan enumerasi asli.

FltQueryDirectoryFileEx mengembalikan nol pada anggota struktur_INFORMATION FILE_XXX yang tidak didukung oleh sistem file.

Penelepon FltQueryDirectoryFileEx harus berjalan di IRQL = PASSIVE_LEVEL dan dengan APC diaktifkan. Untuk informasi selengkapnya, lihat Menonaktifkan APC.