Fungsi ZwQueryInformationFile (wdm.h)

Artikel
02/29/2024

Rutinitas ZwQueryInformationFile mengembalikan berbagai jenis informasi tentang objek file.

Sintaks

NTSYSAPI NTSTATUS ZwQueryInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [out] PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Parameter

[in] FileHandle

Menangani ke objek file. Handel dibuat oleh panggilan yang berhasil ke ZwCreateFile atau ZwOpenFile.

[out] IoStatusBlock

Arahkan ke struktur IO_STATUS_BLOCK yang menerima status penyelesaian akhir dan informasi tentang operasi. Anggota Informasi menerima jumlah byte yang benar-benar ditulis rutinitas ini ke buffer FileInformation .

[out] FileInformation

Arahkan ke buffer yang dialokasikan penelepon tempat rutin menulis informasi yang diminta tentang objek file. Parameter FileInformationClass menentukan jenis informasi yang diminta pemanggil.

[in] Length

Ukuran, dalam byte, dari buffer yang ditujukkan oleh FileInformation.

[in] FileInformationClass

Menentukan jenis informasi yang akan dikembalikan tentang file, dalam buffer yang dituju fileInformation . Perangkat dan driver perantara dapat menentukan salah satu nilai FILE_INFORMATION_CLASS berikut.

nilai FILE_INFORMATION_CLASS	Jenis informasi yang dikembalikan
FileBasicInformation (4)	Struktur FILE_BASIC_INFORMATION . Pemanggil harus telah membuka file dengan bendera FILE_READ_ATTRIBUTES yang ditentukan dalam parameter DesiredAccess .
FileStandardInformation (5)	Struktur FILE_STANDARD_INFORMATION . Pemanggil dapat mengkueri informasi ini selama file terbuka, tanpa persyaratan khusus untuk DesiredAccess.
FileInternalInformation (6)	Struktur FILE_INTERNAL_INFORMATION . Struktur ini menentukan ID file 64-bit yang secara unik mengidentifikasi file di NTFS. Pada sistem file lain, ID file ini tidak dijamin unik.
FileEaInformation (7)	Struktur FILE_EA_INFORMATION . Struktur ini menentukan ukuran blok atribut yang diperluas yang terkait dengan file.
FileAccessInformation (8)	Struktur FILE_ACCESS_INFORMATION . Struktur ini berisi masker akses. Untuk informasi selengkapnya tentang masker akses, lihat ACCESS_MASK.
FileNameInformation (9)	Struktur FILE_NAME_INFORMATION . Struktur dapat berisi jalur lengkap file atau hanya sebagian darinya. Pemanggil dapat mengkueri informasi ini selama file terbuka, tanpa persyaratan khusus untuk DesiredAccess. Untuk informasi selengkapnya tentang sintaks nama file, lihat bagian Keterangan nanti dalam topik ini.
FilePositionInformation (14)	Struktur FILE_POSITION_INFORMATION . Pemanggil harus telah membuka file dengan bendera DesiredAccess FILE_READ_DATA atau FILE_WRITE_DATA yang ditentukan dalam parameter DesiredAccess , dan dengan bendera FILE_SYNCHRONOUS_IO_ALERT atau FILE_SYNCHRONOUS_IO_NONALERT yang ditentukan dalam parameter CreateOptions .
FileModeInformation (16)	Struktur FILE_MODE_INFORMATION . Struktur ini berisi sekumpulan bendera yang menentukan mode tempat file dapat diakses. Bendera ini adalah subset dari opsi yang dapat ditentukan dalam parameter CreateOptions dari rutinitas IoCreateFile .
FileAlignmentInformation (17)	Struktur FILE_ALIGNMENT_INFORMATION . Pemanggil dapat mengkueri informasi ini selama file terbuka, tanpa persyaratan khusus untuk DesiredAccess[. Informasi ini berguna jika file dibuka dengan bendera FILE_NO_INTERMEDIATE_BUFFERING yang ditentukan dalam parameter CreateOptions** .
FileAllInformation (18)	Struktur FILE_ALL_INFORMATION . Dengan menggabungkan beberapa struktur informasi file ke dalam satu struktur, FILE_ALL_INFORMATION mengurangi jumlah kueri yang diperlukan untuk mendapatkan informasi tentang file.
FileNetworkOpenInformation (34)	Struktur FILE_NETWORK_OPEN_INFORMATION . Pemanggil harus telah membuka file dengan bendera FILE_READ_ATTRIBUTES yang ditentukan dalam parameter DesiredAccess .
FileAttributeTagInformation (35)	Struktur FILE_ATTRIBUTE_TAG_INFORMATION . Pemanggil harus telah membuka file dengan bendera FILE_READ_ATTRIBUTES yang ditentukan dalam parameter DesiredAccess .
FileIoPriorityHintInformation (43)	Struktur FILE_IO_PRIORITY_HINT_INFORMATION . Pemanggil harus telah membuka file dengan bendera FILE_READ_DATA yang ditentukan dalam parameter DesiredAccess .
FileIsRemoteDeviceInformation (51)	Struktur FILE_IS_REMOTE_DEVICE_INFORMATION . Pemanggil dapat mengkueri informasi ini selama file terbuka, tanpa persyaratan khusus untuk DesiredAccess.
FileKnownFolderInformation (76)	Struktur FILE_KNOWN_FOLDER_INFORMATION . Tersedia mulai windows Server 2022.

Nilai kembali

ZwQueryInformationFile mengembalikan STATUS_SUCCESS atau kode kesalahan NTSTATUS yang sesuai.

Keterangan

ZwQueryInformationFile mengembalikan informasi tentang objek file yang ditentukan. Perhatikan bahwa ia mengembalikan nol di setiap anggota struktur FILE_XXX_INFORMATION yang tidak didukung oleh perangkat atau sistem file tertentu.

Ketika FileInformationClass = FileNameInformation, nama file dikembalikan dalam struktur FILE_NAME_INFORMATION . Sintaks nama file yang tepat tergantung pada sejumlah faktor:

Jika Anda membuka file dengan mengirimkan jalur lengkap ke ZwCreateFile, ZwQueryInformationFile mengembalikan jalur lengkap tersebut.
Jika handel ObjectAttributes-RootDirectory> dibuka berdasarkan nama dalam panggilan ke ZwCreateFile, dan kemudian file dibuka oleh ZwCreateFile relatif terhadap handel direktori akar ini, ZwQueryInformationFile mengembalikan jalur lengkap.
Jika handel ObjectAttributes-RootDirectory> dibuka oleh ID file (menggunakan bendera FILE_OPEN_BY_FILE_ID) dalam panggilan ke ZwCreateFile, dan kemudian file dibuka oleh ZwCreateFile relatif terhadap handel direktori akar ini, ZwQueryInformationFile mengembalikan jalur relatif.
Namun, jika pengguna memiliki SeChangeNotifyPrivilege, ZwQueryInformationFile mengembalikan jalur lengkap dalam semua kasus.
Jika hanya jalur relatif yang dikembalikan, string nama file tidak akan dimulai dengan garis miring terbelakang.
Jika jalur lengkap dan nama file dikembalikan, string akan dimulai dengan satu garis miring terbelakang, terlepas dari lokasinya. Dengan demikian file C:\dir1\dir2\filename.ext akan muncul sebagai \dir1\dir2\filename.ext, sementara file \server\share\dir1\dir2\filename.ext akan muncul sebagai \server\share\dir1\dir2\filename.ext.

Jika ZwQueryInformationFile gagal karena luapan buffer, driver yang mengimplementasikan FileNameInformation harus mengembalikan sebanyak mungkin karakter WCHAR dari nama file seperti yang akan pas di buffer dan menentukan panjang penuh yang diperlukan dalam parameter FileNameLength dari struktur FILE_NAME_INFORMATION . Anda harus membuat ulang kueri dengan menggunakan panjang nama file sehingga Anda bisa mengambil nama file lengkap. Driver yang tidak mengikuti pola ini mungkin memerlukan peningkatan panjang bertahap hingga mereka mengambil nama file lengkap. Untuk informasi selengkapnya tentang bekerja dengan file, lihat Menggunakan File di Driver.

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

Jika panggilan ke fungsi ini terjadi dalam mode pengguna, Anda harus menggunakan nama "NtQueryInformationFile" alih-alih "ZwQueryInformationFile".

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
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (lihat bagian Keterangan)
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)