Fungsi ZwQueryDirectoryFileEx (ntifs.h)

Artikel
08/07/2023

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

Sintaks

NTSYSAPI NTSTATUS ZwQueryDirectoryFileEx(
  [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]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);

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] QueryFlags

Satu atau beberapa bendera yang terkandung dalam SL_QUERY_DIRECTORY_MASK. Lihat parameter QueryFlags dari NtQueryDirectoryFileEx untuk daftar nilai yang mungkin.

[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 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 ZwQueryDirectoryFileEx untuk handel tertentu. Panggilan berikutnya ke ZwQueryDirectoryFileEx akan menggunakan ekspresi pencarian yang diatur dalam panggilan pertama. Parameter FileName yang diteruskan ke panggilan berikutnya akan diabaikan.

Nilai kembali

ZwQueryDirectoryFileEx mengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai. Kumpulan nilai status kesalahan yang dapat dikembalikan adalah spesifik sistem file. ZwQueryDirectoryFileEx 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

ZwQueryDirectoryFileEx 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 ZwQueryDirectoryFileEx untuk FileHandle tertentu.

Jika setidaknya ada satu entri yang cocok, ZwQueryDirectoryFileEx 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, 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 ZwQueryDirectoryFileEx, 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, ZwQueryDirectoryFileEx mengembalikan struktur FILE_XXX_INFORMATION sebanyak (satu per entri direktori) seperti yang dapat dimuat sepenuhnya dalam buffer yang ditujukkan oleh FileInformation:

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

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

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

Jika ZwQueryDirectoryFileEx 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.

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

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

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.