Fungsi WriteFileGather (fileapi.h)

Artikel
01/10/2024

Mengambil data dari array buffer dan menulis data ke file.

Fungsi mulai menulis data ke file pada posisi yang ditentukan oleh struktur YANG TUMPANG TINDIH . Fungsi WriteFileGather beroperasi secara asinkron.

Sintaks

BOOL WriteFileGather(
  [in]      HANDLE                  hFile,
  [in]      FILE_SEGMENT_ELEMENT [] aSegmentArray,
  [in]      DWORD                   nNumberOfBytesToWrite,
            LPDWORD                 lpReserved,
  [in, out] LPOVERLAPPED            lpOverlapped
);

Parameter

[in] hFile

Handel ke file. Handel file harus dibuat dengan hak akses GENERIC_WRITE , dan bendera FILE_FLAG_OVERLAPPED dan FILE_FLAG_NO_BUFFERING . Untuk informasi selengkapnya, lihat Keamanan File dan Hak Akses.

[in] aSegmentArray

Penunjuk ke array FILE_SEGMENT_ELEMENT buffer struktur yang berisi data. Untuk deskripsi tentang serikat ini, lihat Komentar.

Setiap elemen mewakili satu halaman data.

Catatan

Untuk menentukan ukuran halaman sistem, gunakan fungsi GetSystemInfo .

Array harus berisi elemen yang cukup untuk mewakili byte data nNumberOfBytesToWrite . Misalnya, jika ada 40 KB yang akan ditulis dan ukuran halaman adalah 4 KB, array harus memiliki 10 elemen.

Setiap buffer harus setidaknya ukuran halaman memori sistem dan harus diselaraskan pada batas ukuran halaman memori sistem. Sistem menulis satu halaman memori sistem data dari setiap buffer.

Fungsi ini mengumpulkan data dari buffer dalam urutan berurutan. Misalnya, ia menulis data ke file dari buffer pertama, kemudian buffer kedua, dan seterusnya sampai byte nNumberOfBytesToWrite telah ditulis.

Karena operasi asinkron fungsi ini, tindakan pencegahan harus diambil untuk memastikan bahwa parameter ini selalu mereferensikan memori yang valid selama masa pakai penulisan asinkron. Misalnya, kesalahan pemrograman umum adalah menggunakan penyimpanan tumpukan lokal dan kemudian memungkinkan eksekusi kehabisan cakupan.

[in] nNumberOfBytesToWrite

Jumlah total byte yang akan ditulis. Setiap elemen aSegmentArray berisi potongan satu halaman dari total ini. Karena file harus dibuka dengan FILE_FLAG_NO_BUFFERING, jumlah byte harus merupakan kelipatan dari ukuran sektor sistem file tempat file berada.

Jika nNumberOfBytesToWrite adalah nol (0), fungsi melakukan operasi penulisan null. Perilaku operasi tulis null tergantung pada sistem file yang mendasar. Jika nNumberOfBytesToWrite bukan nol (0) dan offset dan panjang data tempat tulis di luar akhir file saat ini, fungsi WriteFileGather memperluas file.

lpReserved

Parameter ini dicadangkan untuk digunakan di masa mendatang dan harus NULL.

[in, out] lpOverlapped

Penunjuk ke struktur data yang TUMPANG TINDIH .

Fungsi WriteFileGather memerlukan struktur TUMPANG TINDIH yang valid. Parameter lpOverlapped tidak boleh NULL.

Fungsi WriteFileGather mulai menulis data ke file pada posisi yang ditentukan oleh anggota Offset dan OffsetHigh dari struktur YANG TUMPANG TINDIH .

Fungsi WriteFileGather dapat kembali sebelum operasi tulis selesai. Dalam skenario itu, fungsi WriteFileGather mengembalikan nilai nol (0), dan fungsi GetLastError mengembalikan nilai ERROR_IO_PENDING. Operasi asinkron fungsi WriteFileGather ini memungkinkan proses panggilan berlanjut saat operasi tulis selesai.

Anda dapat memanggil fungsi GetOverlappedResult, HasOverlappedIoCompleted, atau GetQueuedCompletionStatus untuk mendapatkan informasi tentang penyelesaian operasi tulis. Untuk informasi selengkapnya, lihat I/O Sinkron dan Asinkron.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol (0). Untuk mendapatkan informasi kesalahan yang diperluas, panggil fungsi GetLastError .

Jika fungsi kembali sebelum operasi tulis selesai, fungsi mengembalikan nol (0), dan fungsi GetLastError mengembalikan ERROR_IO_PENDING.

Keterangan

Fungsi ini tidak didukung untuk aplikasi 32-bit oleh WOW64 pada sistem berbasis Itanium.

Struktur FILE_SEGMENT_ELEMENT didefinisikan sebagai berikut:

typedef union _FILE_SEGMENT_ELEMENT {
    PVOID64   Buffer;
    ULONGLONG Alignment;
}FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;

Menetapkan pointer ke anggota Buffer akan menandatangani perpanjang nilai jika kode dikompilasi sebagai 32-bit; ini dapat merusak aplikasi sadar alamat besar yang berjalan pada sistem yang dikonfigurasi dengan 4-Gigabyte Tuning atau berjalan di bawah WOW64 pada Windows 64-bit. Oleh karena itu, gunakan makro PtrToPtr64 saat menetapkan pointer ke Buffer.

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

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 operasi ditransaksikan.

Persyaratan


Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	fileapi.h (sertakan Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll