Fungsi NtWriteFile (ntifs.h)
ZwWriteFile rutin menulis data ke file terbuka.
Sintaks
__kernel_entry NTSYSCALLAPI NTSTATUS NtWriteFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] PVOID Buffer,
[in] ULONG Length,
[in, optional] PLARGE_INTEGER ByteOffset,
[in, optional] PULONG Key
);
Parameter
[in] FileHandle
Tangani ke objek file. Handel ini dibuat oleh panggilan yang berhasil ke NtCreateFile atau NtOpenFile.
[in, optional] Event
Secara opsional, handel ke objek peristiwa untuk diatur ke status bersinyali setelah operasi tulis selesai. Perangkat dan driver perantara harus mengatur parameter ini ke NULL.
[in, optional] ApcRoutine
Parameter ini dicadangkan. Perangkat dan driver perantara harus mengatur penunjuk ini ke NULL.
[in, optional] ApcContext
Parameter ini dicadangkan. Perangkat dan driver perantara harus mengatur penunjuk ini ke NULL.
[out] IoStatusBlock
Arahkan ke struktur IO_STATUS_BLOCK yang menerima status penyelesaian akhir dan informasi tentang operasi tulis yang diminta. Anggota Informasi menerima jumlah byte yang benar-benar ditulis ke file.
[in] Buffer
Penunjuk ke buffer yang dialokasikan pemanggil yang berisi data untuk ditulis ke file.
[in] Length
Ukuran, dalam byte, dari buffer yang ditujukkan oleh Buffer.
[in, optional] ByteOffset
Penunjuk ke variabel yang menentukan offset byte awal dalam file untuk memulai operasi tulis. Jika Length dan ByteOffset menentukan operasi tulis melewati tanda akhir file saat ini, NtWriteFile secara otomatis memperluas file dan memperbarui tanda akhir file; byte apa pun yang tidak ditulis secara eksplisit antara tanda akhir file lama dan baru tersebut didefinisikan nol.
Jika panggilan ke NtCreateFile hanya mengatur bendera DesiredAccess FILE_APPEND_DATA, ByteOffset diabaikan. Data dalam Buffer yang diberikan, untuk Byte Panjang , ditulis mulai dari akhir file saat ini.
Jika panggilan ke NtCreateFile mengatur salah satu bendera CreateOptions , FILE_SYNCHRONOUS_IO_ALERT atau FILE_SYNCHRONOUS_IO_NONALERT, Manajer I/O mempertahankan posisi file saat ini. Jika demikian, pemanggil NtWriteFile dapat menentukan bahwa offset posisi file saat ini digunakan alih-alih nilai ByteOffset eksplisit. Spesifikasi ini dapat dibuat dengan menggunakan salah satu metode berikut:
- *Tentukan penunjuk ke nilai LARGE_INTEGER dengan anggota HighPart diatur ke -1 dan anggota LowPart diatur ke nilai yang ditentukan sistem FILE_USE_FILE_POINTER_POSITION.
- Berikan penunjuk NULL untuk ByteOffset.
NtWriteFile memperbarui posisi file saat ini dengan menambahkan jumlah byte yang ditulis ketika menyelesaikan operasi tulis, jika menggunakan posisi file saat ini yang dikelola oleh Manajer I/O.
Bahkan ketika Manajer I/O mempertahankan posisi file saat ini, pemanggil dapat mengatur ulang posisi ini dengan meneruskan nilai ByteOffset eksplisit ke NtWriteFile. Melakukan ini secara otomatis mengubah posisi file saat ini ke nilai ByteOffsettersebut, melakukan operasi tulis, dan kemudian memperbarui posisi sesuai dengan jumlah byte yang benar-benar ditulis. Teknik ini memberikan layanan pencarian dan penulisan atom pemanggil.
Dimungkinkan juga untuk menyebabkan operasi tulis dimulai pada akhir file saat ini dengan menentukan byteOffset pointer ke nilai LARGE_INTEGER dengan HighPart diatur ke -1 dan LowPart diatur ke FILE_WRITE_TO_END_OF_FILE. Ini berfungsi terlepas dari apakah Manajer I/O mempertahankan posisi file saat ini.
[in, optional] Key
Perangkat dan driver perantara harus mengatur penunjuk ini ke NULL.
Nilai kembali
NtWriteFile mengembalikan STATUS_SUCCESS pada keberhasilan atau kode kesalahan NTSTATUS yang sesuai pada kegagalan.
Keterangan
Penelepon NtWriteFile harus sudah memanggil NtCreateFile dengan bendera FILE_WRITE_DATA, FILE_APPEND_DATA, atau GENERIC_WRITE yang diatur dalam parameter DesiredAccess . Perhatikan bahwa hanya memiliki akses FILE_APPEND_DATA ke file tidak memungkinkan pemanggil untuk menulis di mana saja dalam file kecuali pada tanda akhir file saat ini, sementara memiliki akses FILE_WRITE_DATA ke file tidak menghalangi pemanggil menulis ke atau di luar akhir file.
Jika panggilan sebelumnya ke NtCreateFile mengatur bendera CreateOptions FILE_NO_INTERMEDIATE_BUFFERING, parameter Length dan ByteOffset ke NtWriteFile harus merupakan integral dari ukuran sektor. Untuk informasi selengkapnya, lihat NtCreateFile.
NtWriteFile memulai operasi tulis ke file di ByteOffset, pada posisi file saat ini, atau pada tanda akhir file. Ini mengakhiri operasi tulis ketika telah menulis Byte Panjang dari Buffer. Jika perlu, ini memperluas panjang file dan mengatur ulang tanda akhir file.
Jika pemanggil membuka file dengan set bendera DesiredAccess SYNCHRONIZE, pemanggil dapat menunggu rutinitas ini untuk mengatur FileHandle yang diberikan ke status bersinyali.
Driver harus memanggil NtWriteFile dalam konteks proses sistem dalam tiga kasus:
- Driver membuat handel file yang diteruskannya ke NtWriteFile.
- NtWriteFile memberi tahu driver penyelesaian I/O melalui peristiwa yang dibuat oleh driver.
- NtWriteFile memberi tahu driver penyelesaian I/O dengan cara rutin panggilan balik APC yang diteruskan driver ke NtWriteFile.
Handel file dan peristiwa hanya valid dalam konteks proses tempat handel dibuat. Oleh karena itu, untuk menghindari lubang keamanan, driver harus membuat file atau handel peristiwa apa pun yang diteruskannya ke NtWriteFile dalam konteks proses sistem alih-alih konteks proses tempat driver berada.
Demikian juga, NtWriteFile harus dipanggil dalam konteks proses sistem jika memberi tahu driver penyelesaian I/O melalui APC, karena APC selalu diaktifkan dalam konteks utas yang mengeluarkan permintaan I/O. Jika driver memanggil NtWriteFile dalam konteks proses selain proses sistem, APC dapat tertunda tanpa batas waktu, atau mungkin tidak menembak sama sekali karena utas asal mungkin tidak pernah memasuki status tunggu yang dapat diperingatkan.
Untuk informasi selengkapnya tentang bekerja dengan file, lihat Menggunakan File di Driver.
Penelepon NtWriteFile 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 "NtWriteFile" alih-alih "ZwWriteFile".
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 |