Fungsi NtQueryInformationFile (ntifs.h)

Artikel
07/11/2023

Rutinitas NtQueryInformationFile mengembalikan berbagai jenis informasi tentang objek file. Lihat juga NtQueryInformationByName, yang dapat digunakan secara lebih efisien untuk beberapa kelas informasi file.

Sintaks

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationFile(
  [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 NtCreateFile atau NtOpenFile, atau ke file yang setara membuat atau membuka rutinitas.

[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 . Driver perangkat dan perantara dapat menentukan salah satu nilai FILE_INFORMATION_CLASS berikut (tercantum dari nilai enum terendah hingga tertinggi):

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.
FileAlternateNameInformation (21)	Struktur FILE_ALL_INFORMATION untuk mengembalikan informasi nama alternatif untuk file (nama format 8.3).
FileStreamInformation (22)	Buffer struktur FILE_STREAM_INFORMATION untuk menghitung aliran data file atau direktori.
FileCompressionInformation (28)	Struktur FILE_COMPRESSION_INFORMATION untuk mengembalikan informasi kompresi untuk 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 .
FileSfioReserveInformation (44)	Struktur FILE_SFIO_RESERVE_INFORMATION .
FileHardLinkInformation (46)	Struktur FILE_LINKS_INFORMATION .
FileNormalizedNameInformation (48)	Struktur FILE_NAME_INFORMATION untuk mengembalikan nama file yang dinormalisasi.
FileIsRemoteDeviceInformation (51)	Struktur FILE_IS_REMOTE_DEVICE_INFORMATION . Pemanggil dapat mengkueri informasi ini selama file terbuka, tanpa persyaratan khusus untuk DesiredAccess.
FileStandardLinkInformation (54)	Struktur FILE_STANDARD_LINK_INFORMATION .
FileIdInformation (59)	Struktur FILE_ID_INFORMATION .
FileDesiredStorageClassInformation (67)	Struktur FILE_DESIRED_STORAGE_CLASS_INFORMATION .
FileStatInformation (68)	FILE_STAT_INFORMATION
FileStatLxInformation (70)	FILE_STAT_LX_INFORMATION
FileCaseSensitiveInformation (71)	Struktur FILE_CASE_SENSITIVE_INFORMATION . Pemanggil harus telah membuka file dengan bendera FILE_READ_ATTRIBUTES yang ditentukan dalam parameter DesiredAccess . Nilai ini tersedia dimulai dengan Windows 10, versi 1803.
FileStorageReserveIdInformation (74)	Struktur FILE_STORAGE_RESERVE_ID_INFORMATION .
FileCaseSensitiveInformationForceAccessCheck (75)	Struktur FILE_CASE_SENSITIVE_INFORMATION . Pemanggil harus telah membuka file dengan bendera FILE_READ_ATTRIBUTES yang ditentukan dalam parameter DesiredAccess . Ini adalah versi khusus dari operasi FileCaseSensitiveInformation yang digunakan untuk memaksa IOManager melakukan pemeriksaan akses untuk driver mode kernel, mirip dengan pemeriksaan yang berlaku untuk pemanggil mode pengguna. Operasi ini hanya dikenali oleh IOManager dan sistem file tidak boleh menerimanya. Nilai ini tersedia dimulai dengan Windows 10, versi 1803.
FileKnownFolderInformation (76)	Struktur FILE_KNOWN_FOLDER_INFORMATION . Tersedia mulai windows Server 2022.

Mengembalikan nilai

NtQueryInformationFile mengembalikan STATUS_SUCCESS atau kode kesalahan NTSTATUS yang sesuai.

Keterangan

NtQueryInformationFile 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 NtCreateFile, NtQueryInformationFile mengembalikan jalur lengkap tersebut.
Jika handel ObjectAttributes-RootDirectory> dibuka berdasarkan nama dalam panggilan ke NtCreateFile, dan kemudian file dibuka oleh NtCreateFile relatif terhadap handel direktori akar ini, NtQueryInformationFile mengembalikan jalur lengkap.
Jika handel ObjectAttributes-RootDirectory> dibuka oleh ID file (menggunakan bendera FILE_OPEN_BY_FILE_ID) dalam panggilan ke NtCreateFile, dan kemudian file dibuka oleh NtCreateFile relatif terhadap handel direktori akar ini, NtQueryInformationFile mengembalikan jalur relatif.
Namun, jika pengguna memiliki SeChangeNotifyPrivilege (dijelaskan dalam dokumentasi Microsoft Windows SDK), NtQueryInformationFile 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 NtQueryInformationFile 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 NtQueryInformationFile harus berjalan di IRQL = PASSIVE_LEVEL dan dengan APC kernel khusus diaktifkan.

Catatan

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