Fungsi NtQueryDirectoryFile (ntifs.h)

Artikel
08/07/2023

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

Sintaks

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFile(
  [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,
  [in]           FILE_INFORMATION_CLASS FileInformationClass,
  [in]           BOOLEAN                ReturnSingleEntry,
  [in, optional] PUNICODE_STRING        FileName,
  [in]           BOOLEAN                RestartScan
);

Parameter

[in] FileHandle

Handel yang dikembalikan oleh NtCreateFile atau NtOpenFile untuk objek file yang mewakili direktori tempat informasi diminta. Objek file harus 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 pemanggil 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 penelepon jika pemanggil menyediakan APC atau jika objek penyelesaian I/O dikaitkan dengan objek file. Ketika operasi selesai, konteks ini diteruskan ke APC, jika salah 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 mengembalikan data, jumlah byte yang ditulis ke buffer FileInformation dikembalikan dalam anggota Informasi struktur.

[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. 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, NtQueryDirectoryFile hanya mengembalikan entri pertama yang ditemukan.

[in, optional] FileName

Penunjuk opsional ke string Unicode yang dialokasikan pemanggil yang berisi nama file (atau beberapa file, jika kartubebas digunakan) dalam direktori yang ditentukan oleh FileHandle. 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 FileName NULL, semua file disertakan.

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

[in] RestartScan

Atur ke TRUE jika pemindaian dimulai pada entri pertama di direktori. Atur ke FALSE jika melanjutkan pemindaian dari panggilan sebelumnya.

Ketika rutinitas NtQueryDirectoryFile dipanggil untuk handel tertentu, parameter RestartScan diperlakukan seolah-olah diatur ke TRUE, terlepas dari nilainya. Pada panggilan NtQueryDirectoryFile berikutnya, nilai parameter RestartScan dihormati.

Nilai kembali

Rutinitas NtQueryDirectoryFilemengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai. Kumpulan nilai status kesalahan yang dapat dikembalikan adalah file-system-specific. NtQueryDirectoryFilejuga mengembalikan jumlah byte yang benar-benar ditulis ke buffer FileInformation yang diberikan di anggota InformasiIoStatusblock. Lihat NtQueryDirectoryFileEx untuk daftar beberapa kemungkinan kode kesalahan.

Keterangan

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

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

Jika setidaknya ada satu entri yang cocok, NtQueryDirectoryFile 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 *terkecil dari yang berikut ini:

Satu entri, jika ReturnSingleEntry adalah TRUE dan FileName adalah 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 NtQueryDirectoryFile, jika struktur yang dibuat untuk entri pertama yang ditemukan terlalu besar untuk masuk ke dalam buffer output, rutin menulis bagian tetap struktur ke buffer output. Rutinitas kemudian menulis ke buffer output sebanyak string FileName yang sesuai. (Bagian tetap dari struktur 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.) Ketika ini terjadi, NtQueryDirectoryFile mengembalikan nilai status yang sesuai seperti STATUS_BUFFER_OVERFLOW.

Pada setiap panggilan, NtQueryDirectoryFile mengembalikan struktur FILE_XXX_INFORMATION sebanyak (satu per entri direktori) seperti yang dapat dimuat sepenuhnya dalam buffer yang diarahkan oleh FileInformation. Pada panggilan pertama, NtQueryDirectoryFile mengembalikan STATUS_SUCCESS hanya jika buffer output berisi setidaknya satu struktur lengkap. Pada panggilan berikutnya, jika buffer output tidak berisi struktur, NtQueryDirectoryFile mengembalikan STATUS_SUCCESS tetapi mengatur IoStatusblock-Information> = 0 untuk memberi tahu pemanggil kondisi ini. Dalam hal ini, penelepon harus mengalokasikan buffer yang lebih besar dan memanggil NtQueryDirectoryFile 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, NtQueryDirectoryFile harus dipanggil setidaknya dua kali untuk menghitung konten seluruh direktori.

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

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

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

NtQueryDirectoryFilemengembalikan nol di setiap anggota struktur FILE_XXX_INFORMATION yang tidak didukung oleh sistem file.

Pemanggil NtQueryDirectoryFile 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 NtQueryDirectoryFile terjadi dalam mode pengguna, Anda harus menggunakan nama "NtQueryDirectoryFile" alih-alih "ZwQueryDirectoryFile".

Untuk panggilan dari driver mode kernel, versi NtXXX dan ZwXXX dari rutinitas Windows Native System Services dapat berperilaku berbeda dalam cara mereka menangani dan menafsirkan 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 XP
Target Platform	Universal
Header	ntifs.h (termasuk Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (lihat bagian Keterangan)
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs, PowerIrpDDis