Fungsi NtSetInformationFile (ntifs.h)

Artikel
07/11/2023

Rutinitas NtSetInformationFile mengubah berbagai jenis informasi tentang objek file.

Sintaks

__kernel_entry NTSYSCALLAPI NTSTATUS NtSetInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [in]  PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Parameter

[in] FileHandle

Tangani ke objek file. Handel ini dibuat oleh panggilan yang berhasil ke NtCreateFile atau NtOpenFile.

[out] IoStatusBlock

Arahkan ke struktur IO_STATUS_BLOCK yang menerima status penyelesaian akhir dan informasi tentang operasi yang diminta. Anggota Informasi menerima jumlah byte yang ditetapkan pada file.

[in] FileInformation

Penunjuk ke buffer yang berisi informasi yang akan diatur untuk file. Struktur khusus dalam buffer ini ditentukan oleh parameter FileInformationClass . Misalnya, jika parameter FileInformationClass diatur ke konstanta FileDispositionInformationEx , parameter ini harus menjadi penunjuk ke struktur FILE_DISPOSITION_INFORMATION_EX .

[in] Length

Ukuran, dalam byte, dari buffer FileInformation .

[in] FileInformationClass

Jenis informasi, disediakan dalam buffer yang ditujukan oleh FileInformation, untuk mengatur file. Perangkat dan driver perantara dapat menentukan salah satu nilai FILE_INFORMATION_CLASS berikut.

nilai FILE_INFORMATION_CLASS	Jenis informasi yang dikembalikan
FileBasicInformation (4)	Ubah informasi yang disediakan dalam struktur FILE_BASIC_INFORMATION . Pemanggil harus membuka file dengan bendera FILE_WRITE_ATTRIBUTES yang diatur dalam parameter DesiredAccess .
FileRenameInformation (10)	Ubah nama file saat ini, yang disediakan dalam struktur FILE_RENAME_INFORMATION . Pemanggil harus memiliki akses DELETE ke file.
FileDispositionInformation (13)	Minta untuk menghapus file saat ditutup atau membatalkan penghapusan yang diminta sebelumnya. Pilihan apakah akan menghapus atau membatalkan disediakan dalam struktur FILE_DISPOSITION_INFORMATION . Pemanggil harus membuka file dengan bendera DELETE yang diatur dalam parameter DesiredAccess .
FilePositionInformation (14)	Ubah informasi file saat ini, yang disimpan dalam struktur FILE_POSITION_INFORMATION .
FileEndOfFileInformation (20)	Ubah informasi akhir file saat ini, yang disediakan dalam struktur FILE_END_OF_FILE_INFORMATION . Operasi dapat memotong atau memperluas file. Pemanggil harus membuka file dengan bendera FILE_WRITE_DATA yang diatur dalam parameter DesiredAccess .
FileValidDataLengthInformation (39)	Ubah panjang data yang valid saat ini untuk file, yang disediakan dalam struktur FILE_VALID_DATA_LENGTH_INFORMATION . File harus berada pada volume NTFS, dan pemanggil harus membuka file dengan bendera FILE_WRITE_DATA yang diatur dalam parameter DesiredAccess . Non-administrator dan pengguna jarak jauh harus memiliki hak istimewa SeManageVolumePrivilege .
FileShortNameInformation (40)	Ubah nama file pendek saat ini, yang disediakan dalam struktur FILE_NAME_INFORMATION . File harus berada pada volume NTFS, dan pemanggil harus telah membuka file dengan bendera Delete DesiredAccess yang diatur dalam parameter DesiredAccess .
FileIoPriorityHintInformation (43)	Ubah petunjuk prioritas IRP default saat ini untuk handel file. Nilai baru disediakan dalam struktur FILE_IO_PRIORITY_HINT_INFORMATION . Struktur ini harus selaras dengan 8 byte.
FileReplaceCompletionInformation (61)	Ubah atau hapus port penyelesaian I/O untuk handel file yang ditentukan. Penelepon memasok pointer ke struktur FILE_COMPLETION_INFORMATION yang menentukan handel port dan kunci penyelesaian. Jika handel port non-NULL, handel ini menentukan port penyelesaian I/O baru untuk dikaitkan dengan handel file. Untuk menghapus port penyelesaian I/O yang terkait dengan handel file, atur handel port dalam struktur ke NULL. Untuk mendapatkan handel port, pemanggil mode pengguna dapat memanggil fungsi CreateIoCompletionPort .
FileDispositionInformationEx (64)	Minta untuk menghapus file atau membatalkan penghapusan yang diminta sebelumnya. Pilihan apakah akan menghapus atau membatalkan, serta pengaturan kapan dan bagaimana penghapusan harus dilakukan, disediakan dalam struktur FILE_DISPOSITION_INFORMATION_EX . Pemanggil harus membuka file dengan bendera DELETE yang diatur dalam parameter DesiredAccess .
FileCaseSensitiveInformation (71)	Ubah informasi yang disediakan dalam struktur FILE_CASE_SENSITIVE_INFORMATION . Pemanggil harus membuka file dengan bendera FILE_WRITE_ATTRIBUTES yang diatur dalam parameter DesiredAccess . Nilai ini tersedia dimulai dengan Windows 10, versi 1803.
FileLinkInformation (72)	Buat tautan keras ke file yang ada, yang ditentukan dalam struktur FILE_LINK_INFORMATION . Tidak semua sistem file mendukung tautan keras; misalnya NTFS melakukan sementara FAT tidak.
FileCaseSensitiveInformationForceAccessCheck (75)	Ubah informasi yang disediakan dalam struktur FILE_CASE_SENSITIVE_INFORMATION . Pemanggil harus membuka file dengan bendera FILE_WRITE_ATTRIBUTES yang diatur 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.

Nilai kembali

NtSetInformationFile mengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai.

Keterangan

NtSetInformationFile mengubah informasi tentang file. Ini mengabaikan anggota struktur FILE_XXX_INFORMATION yang tidak didukung oleh perangkat atau sistem file tertentu.

Jika Anda mengatur FileInformationClass ke FileDispositionInformation, Anda kemudian dapat meneruskan FileHandle ke NtClose tetapi tidak ke rutinitasFileZwXxx lainnya. Karena FileDispositionInformation menyebabkan file ditandai untuk dihapus, ini adalah kesalahan pemrograman untuk mencoba operasi berikutnya pada handel selain menutupnya.

Jika Anda mengatur FileInformationClass ke FilePositionInformation, dan panggilan sebelumnya ke NtCreateFile menyertakan bendera FILE_NO_INTERMEDIATE_BUFFERING dalam parameter CreateOptions , pembatasan tertentu pada anggota CurrentByteOffset dari struktur FILE_POSITION_INFORMATION diberlakukan. Untuk informasi selengkapnya, lihat NtCreateFile.

Jika Anda mengatur FileInformationClass ke FileEndOfFileInformation, dan anggota EndOfFileFILE_END_OF_FILE_INFORMATION menentukan offset di luar tanda akhir file saat ini, NtSetInformationFile memperluas file dan bantalan ekstensi dengan nol.

Untuk informasi selengkapnya tentang bekerja dengan file, lihat Menggunakan File di Driver.

Pemanggil NtSetInformationFile harus berjalan di IRQL = PASSIVE_LEVEL dan dengan APC kernel khusus diaktifkan.

Catatan

Jika panggilan ke fungsi ini terjadi dalam mode pengguna, gunakan nama "NtSetInformationFile" alih-alih "ZwSetInformationFile".

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 rutin NtXxx**** dan ZwXxx****, 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