Fungsi FltQueryDirectoryFile (fltkernel.h)

Artikel
08/07/2023

Rutinitas FltQueryDirectoryFile mengembalikan berbagai jenis informasi tentang file dalam direktori yang ditentukan oleh objek file tertentu. Gunakan FltQueryDirectoryFileEx untuk kontrol kueri yang lebih besar.

Sintaks

NTSTATUS FLTAPI FltQueryDirectoryFile(
  [in]            PFLT_INSTANCE          Instance,
  [in]            PFILE_OBJECT           FileObject,
  [out]           PVOID                  FileInformation,
  [in]            ULONG                  Length,
  [in]            FILE_INFORMATION_CLASS FileInformationClass,
  [in]            BOOLEAN                ReturnSingleEntry,
  [in, optional]  PUNICODE_STRING        FileName,
  [in]            BOOLEAN                RestartScan,
  [out, optional] PULONG                 LengthReturned
);

Parameter

[in] Instance

Penunjuk buram ke instans driver filter yang memulai I/O.

[in] FileObject

Arahkan ke objek file yang mewakili direktori yang akan dipindai.

[out] FileInformation

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

[in] Length

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

[in] FileInformationClass

Jenis informasi yang akan dikembalikan tentang file di direktori. Lihat parameter FileInformationClass dari NtQueryDirectoryFileEx untuk daftar nilai yang mungkin.

[in] ReturnSingleEntry

Atur ke TRUE jika hanya satu entri yang harus dikembalikan, FALSE jika tidak. Jika parameter ini TRUE, FltQueryDirectoryFile hanya mengembalikan entri pertama yang ditemukan.

[in, optional] FileName

Penunjuk ke string Unicode yang dialokasikan pemanggil yang berisi nama file (atau beberapa file, jika kartubebas digunakan) dalam direktori yang ditentukan oleh FileObject. Parameter ini bersifat opsional dan dapat berupa NULL.

Jika FileName bukan NULL, hanya file yang namanya cocok dengan string FileName yang disertakan dalam pemindaian direktori. Jika FileNameNULL, semua file disertakan. Jika RestartScanFALSE, nilai FileName diabaikan.

[in] RestartScan

Atur ke TRUE jika pemindaian dimulai pada entri pertama di direktori. Atur ke FALSE jika melanjutkan pemindaian dari panggilan sebelumnya. Pemanggil harus mengatur parameter ini ke TRUE saat memanggil FltQueryDirectoryFile untuk pertama kalinya.

[out, optional] LengthReturned

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

Nilai kembali

FltQueryDirectoryFile mengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai. Perhatikan bahwa kumpulan nilai status kesalahan yang dapat dikembalikan adalah file-system-specific.

Keterangan

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

Panggilan pertama ke FltQueryDirectoryFile menentukan kumpulan entri yang akan disertakan dalam pemindaian direktori untuk semua panggilan berikutnya, berdasarkan nilai ReturnSingleEntry, FileName, dan RestartScan. Jika setidaknya ada satu entri yang cocok, FltQueryDirectoryFile membuat struktur FILE_XXX_INFORMATION (lihat tabel di atas) untuk setiap entri secara bergantian dan menyimpan struktur ke 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 ReturnSingleEntryadalah TRUE dan FileNameADALAH NULL.
Jumlah entri yang cocok dengan string FileName , jika FileName bukan NULL. (Perhatikan bahwa jika string tidak berisi kartubebas, paling banyak ada satu entri yang cocok.)
Jumlah entri yang informasinya cocok dengan buffer yang ditentukan.
Jumlah entri yang terkandung dalam direktori.

Pada panggilan pertama ke FltQueryDirectoryFile, jika struktur yang dibuat untuk entri pertama ditemukan terlalu besar agar pas dengan buffer output, hanya bagian tetap dari struktur yang dikembalikan. Bagian tetap terdiri dari semua bidang struktur kecuali string FileName akhir. Pada panggilan pertama, tetapi tidak pada panggilan berikutnya, sistem I/O memastikan bahwa buffer cukup besar untuk menahan bagian tetap dari struktur FILE_XXX_INFORMATION yang sesuai. Ketika ini terjadi, FltQueryDirectoryFile mengembalikan nilai status yang sesuai seperti STATUS_BUFFER_OVERFLOW. Juga pada panggilan pertama ke FltQueryDirectoryFile, jika tidak ada file di direktori FileObject yang cocok dengan parameter FileName , FltQueryDirectoryFile mengembalikan nilai status yang sesuai seperti STATUS_NO_SUCH_FILE.

Pada setiap panggilan, FltQueryDirectoryFile mengembalikan struktur FILE_XXX_INFORMATION sebanyak (satu per entri direktori) seperti yang dapat dimuat sepenuhnya dalam buffer yang ditujukkan 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, FltQueryDirectoryFile harus dipanggil setidaknya dua kali untuk menghitung konten seluruh direktori (misalnya, ketika parameter FileName berisi satu atau beberapa karakter kartubebas atau NULL).

Panggilan akhir ke FltQueryDirectoryFile mengembalikan buffer output kosong dan melaporkan nilai status yang sesuai seperti STATUS_NO_MORE_FILES.

Catatan

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

FltQueryDirectoryFile mengembalikan nol pada setiap anggota struktur FILE_XXX_INFORMATION yang tidak didukung oleh sistem file.

Untuk informasi tentang rutinitas kueri informasi file lainnya, lihat Objek File.

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

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista
Target Platform	Universal
Header	fltkernel.h (termasuk Fltkernel.h)
Pustaka	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL (lihat bagian Keterangan)