Fungsi ZwSetInformationFile (wdm.h)

Artikel
03/08/2023

Rutinitas ZwSetInformationFile mengubah berbagai jenis informasi tentang objek file.

Sintaks

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 ke ZwCreateFile atau ZwOpenFile.

[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, yang disediakan dalam buffer yang ditujukkan oleh FileInformation, untuk mengatur file. Perangkat dan driver perantara dapat menentukan salah satu nilai FILE_INFORMATION_CLASS berikut.

FileInformationClass Nilai	Makna
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 telah 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 telah 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 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 telah membuka file dengan bendera Delete DesiredAccess yang diatur dalam parameter DesiredAccess .
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 telah 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. 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 .

Nilai kembali

ZwSetInformationFile mengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai.

Keterangan

ZwSetInformationFile 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 ZwClose tetapi tidak ke rutinitas File ZwXxx lainnya. Karena FileDispositionInformation menyebabkan file ditandai untuk dihapus, itu adalah kesalahan pemrograman untuk mencoba operasi berikutnya pada handel selain menutupnya.

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

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

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

Penelepon ZwSetInformationFile 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 "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 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)