Fungsi WriteFileEx (fileapi.h)

Artikel
03/14/2023

Menulis data ke file atau perangkat input/output (I/O) yang ditentukan. Ini melaporkan status penyelesaiannya secara asinkron, memanggil rutinitas penyelesaian yang ditentukan saat penulisan selesai atau dibatalkan dan utas panggilan dalam status tunggu yang dapat diperingatkan.

Untuk menulis data ke file atau perangkat secara sinkron, gunakan fungsi WriteFile .

Sintaks

BOOL WriteFileEx(
  [in]           HANDLE                          hFile,
  [in, optional] LPCVOID                         lpBuffer,
  [in]           DWORD                           nNumberOfBytesToWrite,
  [in, out]      LPOVERLAPPED                    lpOverlapped,
  [in]           LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parameter

[in] hFile

Handel ke file atau perangkat I/O (misalnya, file, aliran file, disk fisik, volume, buffer konsol, drive pita, soket, sumber daya komunikasi, mailslot, atau pipa).

Parameter ini dapat berupa handel apa pun yang dibuka dengan bendera FILE_FLAG_OVERLAPPED oleh fungsi CreateFile , atau handel soket yang dikembalikan oleh soket atau fungsi terima .

Jangan kaitkan port penyelesaian I/O dengan handel ini. Untuk informasi lebih lanjut, lihat bagian Keterangan.

Handel ini juga harus memiliki hak akses GENERIC_WRITE . Untuk informasi selengkapnya tentang hak akses, lihat Keamanan File dan Hak Akses.

[in, optional] lpBuffer

Penunjuk ke buffer yang berisi data yang akan ditulis ke file atau perangkat.

Buffer ini harus tetap valid selama durasi operasi tulis. Pemanggil tidak boleh menggunakan buffer ini sampai operasi tulis selesai.

[in] nNumberOfBytesToWrite

Jumlah byte yang akan ditulis ke file atau perangkat.

Nilai nol menentukan operasi tulis null. Perilaku operasi tulis null tergantung pada sistem file yang mendasar.

Operasi penulisan pipa di seluruh jaringan dibatasi hingga 65.535 byte per tulis. Untuk informasi selengkapnya mengenai pipa, lihat bagian Keterangan.

[in, out] lpOverlapped

Penunjuk ke struktur data YANG TUMPANG TINDIH yang memasok data yang akan digunakan selama operasi tulis yang tumpang tindih (asinkron).

Untuk file yang mendukung offset byte, Anda harus menentukan offset byte untuk mulai menulis ke file. Anda menentukan offset ini dengan mengatur anggota Offset dan OffsetHigh dari struktur yang TUMPANG TINDIH . Untuk file atau perangkat yang tidak mendukung offset byte, Offset dan OffsetHigh diabaikan.

Untuk menulis ke akhir file, tentukan anggota Offset dan OffsetHigh dari struktur TUMPANG TINDIH sebagai 0xFFFFFFFF. Ini secara fungsional setara dengan sebelumnya memanggil fungsi CreateFile untuk membuka hFile menggunakan akses FILE_APPEND_DATA .

Fungsi WriteFileEx mengabaikan anggota hEvent struktur yang TUMPANG TINDIH. Aplikasi bebas menggunakan anggota tersebut untuk tujuannya sendiri dalam konteks panggilan WriteFileEx . WriteFileEx memberi sinyal penyelesaian operasi penulisannya dengan memanggil, atau mengantre panggilan ke, rutinitas penyelesaian yang diarahkan oleh lpCompletionRoutine, sehingga tidak memerlukan handel peristiwa.

Fungsi WriteFileEx memang menggunakan anggota Internal dan InternalHigh dari struktur yang TUMPANG TINDIH . Anda tidak boleh mengubah nilai anggota ini.

Struktur data yang TUMPANG TINDIH harus tetap valid selama durasi operasi tulis. Seharusnya bukan variabel yang dapat keluar dari cakupan saat operasi tulis tertunda penyelesaiannya.

[in] lpCompletionRoutine

Penunjuk ke rutinitas penyelesaian yang akan dipanggil ketika operasi tulis telah selesai dan utas panggilan dalam status tunggu yang dapat diperingatkan. Untuk informasi selengkapnya tentang rutinitas penyelesaian ini, lihat FileIOCompletionRoutine.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Jika fungsi WriteFileEx berhasil, utas panggilan memiliki operasi I/O asinkron yang tertunda: operasi tulis yang tumpang tindih ke file. Ketika operasi I/O ini selesai, dan utas panggilan diblokir dalam status tunggu yang dapat diperingatkan, sistem operasi memanggil fungsi yang ditunjukkan oleh lpCompletionRoutine, dan penantian WAIT_IO_COMPLETIONselesai dengan kode pengembalian .

Jika fungsi berhasil dan operasi penulisan file selesai, tetapi utas panggilan tidak dalam status tunggu yang dapat diperingatkan, sistem mengantre panggilan ke *lpCompletionRoutine, menahan panggilan hingga utas panggilan memasuki status tunggu yang dapat diperingatkan. Untuk informasi selengkapnya tentang status tunggu yang dapat diperingatkan dan operasi input/output yang tumpang tindih, lihat Tentang Sinkronisasi.

Keterangan

Saat menggunakan WriteFileEx , Anda harus memeriksa GetLastError bahkan ketika fungsi mengembalikan "keberhasilan" untuk memeriksa kondisi yang berhasil tetapi memiliki beberapa hasil yang mungkin ingin Anda ketahui. Misalnya, luapan buffer saat memanggil WriteFileEx akan mengembalikan TRUE, tetapi GetLastError akan melaporkan luapan dengan ERROR_MORE_DATA. Jika panggilan fungsi berhasil dan tidak ada kondisi peringatan, GetLastError akan mengembalikan ERROR_SUCCESS.

Fungsi WriteFileEx akan gagal jika parameter hFile dikaitkan dengan port penyelesaian I/O. Untuk melakukan penulisan menggunakan jenis handel ini, gunakan fungsi WriteFile .

Fungsi WriteFileEx mungkin gagal jika ada terlalu banyak permintaan I/O asinkron yang luar biasa. Jika terjadi kegagalan seperti itu, GetLastError dapat mengembalikan ERROR_INVALID_USER_BUFFER atau ERROR_NOT_ENOUGH_MEMORY.

Untuk membatalkan semua operasi I/O asinkron yang tertunda, gunakan:

CancelIo: Fungsi ini hanya membatalkan operasi yang dikeluarkan oleh utas panggilan untuk handel file yang ditentukan.
CancelIoEx: Fungsi ini membatalkan semua operasi yang dikeluarkan oleh utas untuk handel file yang ditentukan.

Gunakan CancelSynchronousIo untuk membatalkan operasi I/O sinkron yang tertunda.

Operasi I/O yang dibatalkan selesai dengan kesalahan ERROR_OPERATION_ABORTED.

Jika bagian dari file yang ditentukan oleh hFile dikunci oleh proses lain, dan operasi tulis yang ditentukan tumpang tindih dengan bagian terkunci, WriteFileEx gagal.

Saat menulis ke file, waktu tulis terakhir tidak sepenuhnya diperbarui sampai semua handel yang digunakan untuk menulis telah ditutup. Oleh karena itu, untuk memastikan waktu penulisan terakhir yang akurat, tutup handel file segera setelah menulis ke file.

Mengakses buffer output saat operasi tulis menggunakan buffer dapat menyebabkan kerusakan data yang ditulis dari buffer tersebut. Aplikasi tidak boleh menulis ke, mengalokasikan ulang, atau membebaskan buffer output yang digunakan operasi tulis hingga operasi tulis selesai.

Perhatikan bahwa stempel waktu mungkin tidak diperbarui dengan benar untuk file jarak jauh. Untuk memastikan hasil yang konsisten, gunakan I/O yang tidak dibuffer.

Sistem menafsirkan nol byte untuk ditulis karena menentukan operasi penulisan null dan WriteFile tidak memotong atau memperluas file. Untuk memotong atau memperluas file, gunakan fungsi SetEndOfFile .

Aplikasi menggunakan fungsi WaitForSingleObjectEx, WaitForMultipleObjectsEx, MsgWaitForMultipleObjectsEx, SignalObjectAndWait, dan SleepEx untuk memasuki status tunggu yang dapat diperingatkan. Untuk informasi selengkapnya tentang status tunggu yang dapat diperingatkan dan operasi I/O yang tumpang tindih, lihat Tentang Sinkronisasi.

Jika Anda menulis langsung ke volume yang memiliki sistem file yang dipasang, Anda harus terlebih dahulu mendapatkan akses eksklusif ke volume. Jika tidak, Anda berisiko menyebabkan kerusakan data atau ketidakstabilan sistem, karena penulisan aplikasi Anda mungkin bertentangan dengan perubahan lain yang berasal dari sistem file dan membiarkan konten volume dalam keadaan tidak konsisten. Untuk mencegah masalah ini, perubahan berikut telah dilakukan di Windows Vista dan yang lebih baru:

Tulis pada handel volume akan berhasil jika volume tidak memiliki sistem file yang dipasang, atau jika salah satu kondisi berikut ini benar:
- Sektor yang akan ditulis adalah sektor boot.
- Sektor yang akan ditulis untuk berada di luar ruang sistem file.
- Anda telah secara eksplisit mengunci atau melepas volume dengan menggunakan FSCTL_LOCK_VOLUME atau FSCTL_DISMOUNT_VOLUME.
- Volume tidak memiliki sistem file aktual. (Dengan kata lain, ia memiliki sistem file RAW yang dipasang.)
Penulisan pada handel disk akan berhasil jika salah satu kondisi berikut ini benar:
- Sektor yang akan ditulis tidak termasuk dalam jangkauan volume.
- Sektor yang akan ditulis berada dalam volume yang dipasang, tetapi Anda telah secara eksplisit mengunci atau melepas volume dengan menggunakan FSCTL_LOCK_VOLUME atau FSCTL_DISMOUNT_VOLUME.
- Sektor yang akan ditulis untuk jatuh dalam volume yang tidak memiliki sistem file yang dipasang selain RAW.

Ada persyaratan ketat untuk berhasil bekerja dengan file yang dibuka dengan CreateFile menggunakan FILE_FLAG_NO_BUFFERING. Untuk detailnya lihat Buffering File.

Di Windows 8 dan Windows Server 2012, fungsi ini didukung oleh teknologi berikut.

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Ya
SMB 3.0 Transparent Failover (TFO)	Ya
SMB 3.0 dengan Scale-out File Shares (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

Operasi yang Ditransaksikan

Jika ada transaksi yang terikat ke handel file, maka penulisan file akan ditransaksikan. Untuk informasi selengkapnya, lihat Tentang Transactional NTFS.

Contoh

Misalnya, lihat Server Pipa Bernama Menggunakan Rutinitas Penyelesaian.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	fileapi.h (sertakan Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll