Fungsi ZwSetInformationFile (wdm.h)

Artikel
11/07/2024

ZwSetInformationFile rutin mengubah berbagai jenis informasi tentang objek file.

Sintaksis

NTSYSAPI NTSTATUS ZwSetInformationFile(
  [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 untuk ZwCreateFile atau ZwOpenFile.

[out] IoStatusBlock

Penunjuk 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 FileDispositionInformationEx konstanta, parameter ini harus menjadi penunjuk ke struktur FILE_DISPOSITION_INFORMATION_EX.

[in] Length

Ukuran, dalam byte, dari buffer FileInformation.

[in] FileInformationClass

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

Nilai FileInformationClass	Arti
FileBasicInformation	Ubah informasi yang disediakan dalam struktur FILE_BASIC_INFORMATION. Pemanggil harus telah membuka file dengan bendera FILE_WRITE_ATTRIBUTES yang diatur dalam parameter DesiredAccess.
FileDispositionInformation	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.
FileDispositionInformationEx	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 telah membuka file dengan bendera DELETE** yang diatur dalam parameter DesiredAccess.
FileEndOfFileInformation	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.
FileIoPriorityHintInformation	Ubah petunjuk prioritas IRP default saat ini untuk handel file. Nilai baru disediakan dalam struktur FILE_IO_PRIORITY_HINT_INFORMATION. Struktur ini harus selaras 8-byte.
FileLinkInformation	Buat tautan keras ke file yang sudah ada, yang ditentukan dalam struktur FILE_LINK_INFORMATION. Tidak semua sistem file mendukung tautan keras; misalnya NTFS melakukan sementara FAT tidak.
FilePositionInformation	Ubah informasi file saat ini, yang disimpan dalam struktur FILE_POSITION_INFORMATION.
FileRenameInformation	Ubah nama file saat ini, yang disediakan dalam struktur FILE_RENAME_INFORMATION. Pemanggil harus memiliki akses DELETE ke file.
FileShortNameInformation	Ubah nama file pendek saat ini, yang disediakan dalam struktur FILE_NAME_INFORMATION. File harus berada pada volume NTFS, dan pemanggil harus membuka file dengan bendera DesiredAccess DELETE yang diatur dalam parameter DesiredAccess.
FileIoCompletionNotificationInformation	Ubah bendera pemberitahuan penyelesaian IO file. Mendukung bendera yang sama dengan SetFileCompletionNotificationModes.
FileValidDataLengthInformation	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.
FileReplaceCompletionInformation	Ubah atau hapus port penyelesaian I/O untuk handel file yang ditentukan. Pemanggil 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.

Mengembalikan nilai

ZwSetInformationFile mengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai.

Komentar

ZwSetInformationFile mengubah informasi tentang file. Ini mengabaikan anggota struktur_INFORMATION FILE_XXX yang tidak didukung oleh perangkat atau sistem file tertentu.

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

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

Jika Anda mengatur FileInformationClass keFileEndOfFileInformation , dan EndOfFile anggota FILE_END_OF_FILE_INFORMATION menentukan offset di luar tanda akhir file saat ini, ZwSetInformationFile memperluas file dan menyatukan ekstensi dengan nol.

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

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

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

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
Platform Target	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	HwStorPortProhibitedDIs (storport), PowerIrpDDis(wdm)