Fungsi ZwQueryDirectoryFile (ntifs.h)

Artikel
07/11/2023

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

Sintaks

NTSYSAPI NTSTATUS ZwQueryDirectoryFile(
  [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 ZwCreateFile atau ZwOpenFile 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 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 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, ZwQueryDirectoryFile 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:

Jika FileName bukan NULL, hanya file yang namanya cocok dengan string FileName yang disertakan dalam pemindaian direktori.
Jika FileNameNULL, semua file disertakan jika ReturnSingleEntryADALAH FALSE; satu file disertakan jika ReturnSingleEntry ADALAH TRUE.

FileName digunakan sebagai ekspresi pencarian dan diambil pada panggilan pertama ke ZwQueryDirectoryFile untuk handel tertentu. Panggilan berikutnya ke ZwQueryDirectoryFile 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 ZwQueryDirectoryFile dipanggil untuk handel tertentu, parameter RestartScan diperlakukan seolah-olah diatur ke TRUE, terlepas dari nilainya. Pada panggilan ZwQueryDirectoryFile berikutnya, nilai parameter RestartScan dihormati.

Nilai kembali

Rutinitas ZwQueryDirectoryFile mengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai. Kumpulan nilai status kesalahan yang dapat dikembalikan adalah spesifik sistem file. ZwQueryDirectoryFile juga 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 ZwQueryDirectoryFile 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 ZwQueryDirectoryFile untuk FileHandle tertentu.

Jika setidaknya ada satu entri yang cocok, ZwQueryDirectoryFile 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 ReturnSingleEntry adalah TRUE dan FileName adalah NULL.
Jumlah entri yang cocok dengan string FileName , jika FileName bukan NULL. 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 ZwQueryDirectoryFile, jika struktur yang dibuatnya untuk entri pertama yang ditemukan terlalu besar untuk masuk ke dalam 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, ZwQueryDirectoryFile mengembalikan struktur FILE_XXX_INFORMATION sebanyak (satu per entri direktori) seperti yang dapat dimuat sepenuhnya dalam buffer yang ditujukkan oleh FileInformation:

Pada panggilan pertama, ZwQueryDirectoryFile mengembalikan STATUS_SUCCESS hanya jika buffer output berisi setidaknya satu struktur lengkap.
Pada panggilan berikutnya, jika buffer output tidak berisi struktur, ZwQueryDirectoryFile 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 ZwQueryDirectoryFile 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, ZwQueryDirectoryFile harus dipanggil setidaknya dua kali untuk menghitung konten seluruh direktori.

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

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

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

ZwQueryDirectoryFile mengembalikan nol dalam setiap anggota struktur FILE_XXX_INFORMATION yang tidak didukung oleh sistem file.

Penelepon ZwQueryDirectoryFile 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 ZwQueryDirectoryFile 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(storport), PowerIrpDDis(wdm)