Fungsi ReadFileScatter (fileapi.h)

Artikel
01/10/2024

Membaca data dari file dan menyimpannya dalam array buffer.

Fungsi mulai membaca data dari file pada posisi yang ditentukan oleh struktur TUMPANG TINDIH . Fungsi ReadFileScatter beroperasi secara asinkron.

Sintaks

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

Parameter

[in] hFile

Handel ke file yang akan dibaca.

Handel file harus dibuat dengan kanan GENERIC_READ , 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 menerima data. Untuk deskripsi tentang serikat ini, lihat Keterangan.

Setiap elemen mewakili satu halaman data.

Catatan

Untuk menentukan ukuran halaman sistem, gunakan GetSystemInfo.

Array harus berisi elemen yang cukup untuk mewakili byte data nNumberOfBytesToRead . Misalnya, jika ada 40 KB yang akan dibaca 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 membaca satu halaman memori sistem data ke dalam setiap buffer.

Fungsi menyimpan data dalam buffer dalam urutan berurutan. Misalnya, ia menyimpan data ke buffer pertama, kemudian ke buffer kedua, dan seterusnya sampai setiap buffer terisi dan semua data disimpan, atau byte nNumberOfBytesToRead telah dibaca.

[in] nNumberOfBytesToRead

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

lpReserved

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

[in, out] lpOverlapped

Penunjuk ke struktur data YANG TUMPANG TINDIH .

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

Fungsi ReadFileScatter mulai membaca data dari file pada posisi yang ditentukan oleh anggota Offset dan OffsetHigh dari struktur TUMPANG TINDIH .

Fungsi ReadFileScatter dapat kembali sebelum operasi baca selesai. Dalam skenario tersebut, fungsi ReadFileScatter mengembalikan nilai 0 (nol), dan fungsi GetLastError mengembalikan nilai ERROR_IO_PENDING. Operasi asinkron ReadFileScatter ini memungkinkan proses panggilan berlanjut saat operasi baca selesai. Anda dapat memanggil fungsi GetOverlappedResult, HasOverlappedIoCompleted, atau GetQueuedCompletionStatus untuk mendapatkan informasi tentang penyelesaian operasi baca. 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 ReadFileScatter mencoba membaca melewati end-of-file (EOF), panggilan ke GetOverlappedResult untuk operasi tersebut mengembalikan false dan GetLastError mengembalikan ERROR_HANDLE_EOF.

Jika fungsi kembali sebelum operasi baca selesai, fungsi mengembalikan nol (0), dan 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 penunjuk ke anggota Buffer akan memperpanjang 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.

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 Berbagi File Peluasan Skala (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 fungsi mengembalikan data dari tampilan file yang ditransaksikan. Handel baca yang ditransaksikan dijamin untuk menampilkan tampilan file yang sama selama durasi handel.

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