Bagikan melalui

Fungsi ZwQueryDirectoryFile (ntifs.h)

  • Artikel

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

Sintaksis

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 NULL non-untuk Peristiwa atau ApcRoutine.

[in, optional] Event

Handel opsional untuk peristiwa yang dibuat pemanggil. 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 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 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 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 NULL. Ini harus NULL jika ApcRoutine 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 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 dalam direktori. Lihat parameter FileInformationClassNtQueryDirectoryFileEx untuk daftar nilai yang mungkin.

[in] ReturnSingleEntry

Atur ke TRUE jika hanya satu entri yang harus dikembalikan, FALSE sebaliknya. 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 wildcard digunakan) dalam direktori yang ditentukan oleh FileHandle. Parameter ini bersifat opsional:

  • Jika FileName tidak NULL, hanya file yang namanya cocok dengan string FileName yang disertakan dalam pemindaian direktori.
  • Jika FileName NULL , semua file disertakan jika ReturnSingleEntry FALSE; satu file disertakan jika ReturnSingleEntry 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 dalam 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 memulai kembali 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.

Mengembalikan nilai

Rutinitas ZwQueryDirectoryFile mengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai. Kumpulan nilai status kesalahan yang dapat dikembalikan adalah file khusus sistem. ZwQueryDirectoryFile juga mengembalikan jumlah byte yang benar-benar ditulis ke buffer FileInformation yang diberikan di Informasi anggota IoStatusBlock. Lihat NtQueryDirectoryFileEx untuk daftar beberapa kemungkinan kode kesalahan.

Komentar

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 ada setidaknya satu entri yang cocok, ZwQueryDirectoryFile membuat struktur_INFORMATION FILE_XXX 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 ReturnSingleEntryTRUE dan FileNameNULL .
  • Jumlah entri yang cocok dengan string FileName, jika FileName tidak 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 ZwQueryDirectoryFile, jika struktur yang dibuatnya untuk entri pertama yang ditemukan terlalu besar untuk dimasukkan ke dalam buffer output, rutinitas ini melakukan hal berikut:

  • Menulis bagian tetap dari struktur untuk 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_INFORMATION FILE_XXX yang sesuai.
  • Menulis ke buffer output sebanyak string FileName sesuai keinginan.
  • Mengembalikan nilai status yang sesuai seperti STATUS_BUFFER_OVERFLOW.

Pada setiap panggilan, ZwQueryDirectoryFile mengembalikan struktur_INFORMATION XXX FILE_(satu per entri direktori) seperti yang dapat dimuat sepenuhnya dalam buffer yang ditunjukkan 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 memanggilZwQueryDirectoryFile , 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 lain mengubah konten direktori tersebut, perubahan apa pun mungkin atau mungkin tidak terlihat, tergantung pada waktu operasi.

ZwQueryDirectoryFile mengembalikan nol dalam setiap anggota struktur_INFORMATION FILE_XXX 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.

Nota

Jika panggilan ke fungsi ZwQueryDirectoryFile terjadi dalam mode pengguna, Anda harus menggunakan nama "NtQueryDirectoryFile" alih-alih "ZwQueryDirectoryFile".

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

Persyaratan

Syarat Nilai
klien minimum yang didukung Windows XP.
Platform Target Universal
Header ntifs.h (termasuk Ntifs.h)
Pustaka NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (lihat bagian Keterangan)
aturan kepatuhan DDI HwStorPortProhibitedDIs (storport), PowerIrpDDis(wdm)

Lihat juga

FILE_BOTH_DIR_INFORMATION

FILE_DIRECTORY_INFORMATION

FILE_FULL_DIR_INFORMATION

FILE_ID_BOTH_DIR_INFORMATION

FILE_ID_FULL_DIR_INFORMATION

FILE_NAMES_INFORMATION

FILE_OBJECTID_INFORMATION

FILE_REPARSE_POINT_INFORMATION

UNICODE_STRING

Menggunakan Versi Nt dan Zw dari Rutinitas Layanan Sistem Asli

ZwCreateFile

ZwQueryDirectoryFileEx

ZwOpenFile