Fungsi NtQueryDirectoryFileEx (ntifs.h)

Artikel
03/10/2023

Rutinitas NtQueryDirectoryFileEx mengembalikan berbagai jenis informasi tentang file dalam direktori yang ditentukan oleh handel file tertentu.

Sintaks

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFileEx(
  [in]           HANDLE                 FileHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [out]          PIO_STATUS_BLOCK       IoStatusBlock,
  [out]          PVOID                  FileInformation,
  [in]           ULONG                  Length,
                 FILE_INFORMATION_CLASS FileInformationClass,
  [in]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);

Parameter

[in] FileHandle

Handel yang dikembalikan oleh NtCreateFile atau NtOpenFile untuk objek file yang mewakili direktori tempat informasi diminta. Objek file harus telah dibuka untuk I/O asinkron jika pemanggil menentukan nilai non-NULL untuk Peristiwa atau ApcRoutine.

[in, optional] Event

Handel opsional untuk peristiwa yang dibuat penelepon. Jika parameter ini disediakan, pemanggil akan dimasukkan ke dalam status tunggu hingga operasi yang diminta selesai dan peristiwa yang diberikan diatur ke status Sinyal. Parameter ini bersifat opsional dan dapat berupa NULL. Ini harus NULL jika penelepon akan menunggu FileHandle diatur ke status Sinyal.

[in, optional] ApcRoutine

Alamat rutinitas APC opsional yang disediakan penelepon untuk dipanggil ketika operasi yang diminta selesai. Parameter ini bersifat opsional dan dapat berupa NULL. Jika ada objek penyelesaian I/O yang terkait dengan objek file, parameter ini harus NULL.

[in, optional] ApcContext

Penunjuk opsional ke area konteks yang ditentukan pemanggil jika pemanggil memasok APC atau jika objek penyelesaian I/O dikaitkan dengan objek file. Ketika operasi selesai, konteks ini diteruskan ke APC, jika satu ditentukan, atau disertakan sebagai bagian dari pesan penyelesaian yang diposting Manajer I/O ke objek penyelesaian I/O terkait.

Parameter ini bersifat opsional dan dapat berupa NULL. Ini harus NULL jika ApcRoutine ADALAH NULL dan tidak ada objek penyelesaian I/O yang terkait dengan objek file.

[out] IoStatusBlock

Penunjuk ke struktur IO_STATUS_BLOCK yang menerima status penyelesaian akhir dan informasi tentang operasi. Untuk panggilan yang berhasil yang mengembalikan data, jumlah byte yang ditulis ke buffer FileInformation dikembalikan di anggota Informasi struktur.

[out] FileInformation

Penunjuk ke buffer output 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 ditujukkan oleh FileInformation. Pemanggil harus mengatur parameter ini sesuai dengan FileInformationClass yang diberikan.

FileInformationClass

Jenis informasi yang akan dikembalikan tentang file di direktori. Jenis informasi yang akan dikembalikan tentang file di direktori. FileInformationClass bisa menjadi salah satu nilai FILE_INFORMATION_CLASS berikut.

Nilai	Makna
FileDirectoryInformation (1)	Mengembalikan struktur FILE_DIRECTORY_INFORMATION untuk setiap file.
FileFullDirectoryInformation (2)	Mengembalikan struktur FILE_FULL_DIR_INFORMATION untuk setiap file.
FileBothDirectoryInformation (3)	Mengembalikan struktur FILE_BOTH_DIR_INFORMATION untuk setiap file.
FileNamesInformation (12)	Mengembalikan struktur FILE_NAMES_INFORMATION untuk setiap file.
FileObjectIdInformation (29)	Mengembalikan struktur FILE_OBJECTID_INFORMATION untuk setiap file yang memiliki ID objek pada volume. Kelas informasi ini hanya berlaku untuk direktori khusus "\$Extend\$ObjId:$O:$INDEX_ALLOCATION" pada volume NTFS.
FileQuotaInformation (32)	Mengembalikan struktur FILE_QUOTA_INFORMATION tunggal untuk setiap pengguna pada volume yang memiliki kuota yang diterapkan. Kelas informasi ini hanya berlaku untuk direktori khusus "\$Extend\$Quota:$Q:$INDEX_ALLOCATION" pada volume NTFS.
FileReparsePointInformation (33)	Mengembalikan struktur FILE_REPARSE_POINT_INFORMATION tunggal untuk setiap file yang memiliki titik pemisahan ulang pada volume. Kelas informasi ini hanya berlaku untuk direktori khusus "\$Extend\$Reparse:$R:$INDEX_ALLOCATION" pada volume NTFS dan ReFS.
FileIdBothDirectoryInformation (37)	Mengembalikan struktur FILE_ID_BOTH_DIR_INFORMATION untuk setiap file.
FileIdFullDirectoryInformation (38)	Mengembalikan struktur FILE_ID_FULL_DIR_INFORMATION untuk setiap file.
FileIdGlobalTxDirectoryInformation (50)	Mengembalikan struktur FILE_ID_GLOBAL_TX_DIR_INFORMATION untuk setiap file.
FileIdExtdDirectoryInformation (60)	Mengembalikan struktur FILE_ID_EXTD_DIR_INFORMATION untuk setiap file.
FileIdExtdBothDirectoryInformation (63)	Mengembalikan struktur FILE_ID_EXTD_BOTH_DIR_INFORMATION untuk setiap file.

[in] QueryFlags

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

Nilai	Makna
SL_RESTART_SCAN (0x00000001)	Pemindaian akan dimulai pada entri pertama dalam direktori. Jika bendera ini tidak diatur, pemindaian akan dilanjutkan dari tempat kueri terakhir berakhir.
SL_RETURN_SINGLE_ENTRY (0x00000002)	Biasanya buffer kembali dikemas dengan entri direktori yang cocok sebanyak mungkin. Jika bendera ini diatur, sistem file hanya akan mengembalikan satu entri direktori pada satu waktu. Ini membuat operasi kurang efisien.
SL_INDEX_SPECIFIED (0x00000004)	Pemindaian harus dimulai pada posisi terindeks tertentu di direktori. Bendera ini hanya dapat diatur jika Anda membuat IRP 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)	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 per FileObject. Ketika beberapa utas melakukan kueri menggunakan FileObject yang sama, akses ke struktur per-FileObject adalah utas tunggal untuk mencegah kerusakan status kursor. Bendera ini memberi tahu sistem file untuk tidak memperbarui informasi status kursor per FileObject 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 benar. Jika bendera ini digunakan di dalam transaksi TxF, operasi akan gagal. Tidak semua sistem file mendukung bendera ini.

[in, optional] FileName

Penunjuk opsional ke string Unicode yang dialokasikan pemanggil yang berisi nama file (atau beberapa file, jika wildcard digunakan) dalam direktori yang ditentukan oleh FileHandle. Parameter ini bersifat opsional:

Jika FileName bukan NULL, hanya file yang namanya cocok dengan string FileName yang disertakan dalam pemindaian direktori.
Jika FileName NULL:
- Jika SL_RETURN_SINGLE_ENTRY tidak diatur dalam QueryFlags, semua file disertakan.
- Jika SL_RETURN_SINGLE_ENTRY diatur, hanya satu file yang disertakan.

FileName digunakan sebagai ekspresi pencarian dan diambil pada panggilan pertama ke NtQueryDirectoryFileEx untuk handel tertentu. Panggilan berikutnya ke NtQueryDirectoryFileEx akan menggunakan ekspresi pencarian yang diatur dalam panggilan pertama. Parameter FileName yang diteruskan ke panggilan berikutnya akan diabaikan.

Nilai kembali

NtQueryDirectoryFileEx mengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai. Kumpulan nilai status kesalahan yang dapat dikembalikan adalah file khusus sistem. NtQueryDirectoryFileEx juga mengembalikan jumlah byte yang benar-benar ditulis ke buffer FileInformation yang diberikan di anggota InformasiIoStatusBlock. Beberapa kemungkinan kode kesalahan dan alasannya mungkin adalah sebagai berikut:

Menampilkan kode	Makna
STATUS_BUFFER_OVERFLOW	Buffer output tidak cukup besar untuk mengembalikan nama file lengkap.
STATUS_BUFFER_TOO_SMALL	Buffer output tidak cukup besar untuk setidaknya struktur dasar yang diidentifikasi oleh FileInformationClass.
STATUS_INVALID_INFO_CLASS	FileInformationClass yang tidak valid ditentukan, atau kelas informasi hanya valid untuk kondisi khusus (misalnya, hanya berlaku untuk direktori khusus).
STATUS_INVALID_PARAMETER	Salah satu parameter tidak valid untuk sistem file.

Keterangan

NtQueryDirectoryFileEx mengembalikan informasi tentang file yang terkandung dalam direktori yang diwakili oleh FileHandle.

Jika disediakan, FileName menentukan entri yang disertakan dalam pemindaian direktori untuk semua panggilan berikutnya ke NtQueryDirectoryFileEx untuk FileHandle tertentu.

Jika setidaknya ada satu entri yang cocok, NtQueryDirectoryFileEx membuat struktur FILE_XXX_INFORMATION untuk setiap entri dan menyimpannya di 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 SL_RETURN_SINGLE_ENTRY diatur dalam QueryFlags dan FileName adalah NULL.
Jumlah entri yang cocok dengan string FileName , jika FileName bukan NULL. Jika string tidak berisi kartubebas, mungkin ada paling banyak satu entri yang cocok.
Jumlah entri yang informasinya cocok dengan buffer yang ditentukan.
Jumlah entri yang terkandung dalam direktori.

Pada panggilan pertama ke NtQueryDirectoryFileEx, jika struktur yang dibuatnya untuk entri pertama yang ditemukan terlalu besar agar pas dengan buffer output, rutinitas ini melakukan hal berikut:

Menulis bagian tetap dari struktur ke buffer output FileInformation. Bagian tetap terdiri dari semua bidang 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.
Menulis ke buffer output sebanyak string FileName yang sesuai.
Mengembalikan nilai status yang sesuai seperti STATUS_BUFFER_OVERFLOW.

Pada setiap panggilan, NtQueryDirectoryFileEx mengembalikan struktur FILE_XXX_INFORMATION sebanyak (satu per entri direktori) seperti yang dapat dimuat sepenuhnya dalam buffer yang ditujukkan oleh FileInformation:

Pada panggilan pertama, NtQueryDirectoryFileEx mengembalikan STATUS_SUCCESS hanya jika buffer output berisi setidaknya satu struktur lengkap.
Pada panggilan berikutnya, jika buffer output tidak berisi struktur, NtQueryDirectoryFileEx mengembalikan STATUS_SUCCESS tetapi mengatur IoStatusBlock-Information> = 0 untuk memberi tahu pemanggil kondisi ini. Dalam hal ini, pemanggil harus mengalokasikan buffer yang lebih besar dan memanggil NtQueryDirectoryFileEx lagi. 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, NtQueryDirectoryFileEx harus dipanggil setidaknya dua kali untuk menghitung konten seluruh direktori.

Saat memanggil NtQueryDirectoryFileEx, Anda mungkin melihat perubahan yang dilakukan pada direktori yang terjadi secara paralel dengan panggilan NtQueryDirectoryFileEx . Perilaku ini tergantung pada implementasi sistem file yang mendasar.

Panggilan terakhir ke NtQueryDirectoryFileEx mengembalikan buffer output kosong dan melaporkan nilai status yang sesuai seperti STATUS_NO_MORE_FILES.

Jika NtQueryDirectoryFileEx dipanggil beberapa kali pada direktori yang sama dan beberapa operasi lain mengubah konten direktori tersebut, perubahan apa pun mungkin atau mungkin tidak terlihat, tergantung pada waktu operasi.

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

Penelepon NtQueryDirectoryFileEx harus berjalan di IRQL = PASSIVE_LEVEL dan dengan APC kernel khusus diaktifkan.

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

Catatan

Jika panggilan ke fungsi NtQueryDirectoryFileEx terjadi dalam mode kernel, Anda harus menggunakan nama "ZwQueryDirectoryFileEx" alih-alih "NtQueryDirectoryFileEx".

Untuk panggilan dari driver mode kernel, versi NtXxx dan ZwXxx dari rutinItas Windows Native System Services dapat berperilaku berbeda dalam cara mereka menangani dan menginterpretasikan parameter input. Untuk informasi selengkapnya tentang hubungan antara versi NtXxx dan ZwXxx dari rutinitas, lihat Menggunakan Versi Nt dan Zw dari Rutinitas Layanan Sistem Asli.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 10 versi 1709
Header	ntifs.h
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (lihat bagian Keterangan)