Fungsi ReadFileEx (fileapi.h)

Artikel
08/23/2023

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

Untuk membaca data dari file atau perangkat secara sinkron, gunakan fungsi ReadFile .

Sintaks

BOOL ReadFileEx(
  [in]            HANDLE                          hFile,
  [out, optional] LPVOID                          lpBuffer,
  [in]            DWORD                           nNumberOfBytesToRead,
  [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 .

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

[out, optional] lpBuffer

Penunjuk ke buffer yang menerima data yang dibaca dari file atau perangkat.

Buffer ini harus tetap valid selama durasi operasi baca. Aplikasi tidak boleh menggunakan buffer ini sampai operasi baca selesai.

[in] nNumberOfBytesToRead

Jumlah byte yang akan dibaca.

[in, out] lpOverlapped

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

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

Fungsi ReadFileEx mengabaikan anggota hEvent struktur yang TUMPANG TINDIH. Aplikasi bebas menggunakan anggota tersebut untuk tujuannya sendiri dalam konteks panggilan ReadFileEx . ReadFileEx menandakan penyelesaian operasi bacanya dengan memanggil, atau mengantre panggilan ke, rutinitas penyelesaian yang diarahkan oleh lpCompletionRoutine, sehingga tidak memerlukan penanganan peristiwa.

Fungsi ReadFileEx memang menggunakan anggota Internal dan InternalHigh struktur YANG TUMPANG TINDIH. Aplikasi tidak boleh mengatur anggota ini.

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

[in] lpCompletionRoutine

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

Mengembalikan nilai

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 berhasil, utas panggilan memiliki operasi I/O asinkron tertunda: operasi baca yang tumpang tindih dari file. Ketika operasi I/O ini selesai, dan utas panggilan diblokir dalam status tunggu yang dapat diperingatkan, sistem memanggil fungsi yang ditunjukkan oleh lpCompletionRoutine, dan status tunggu selesai dengan kode pengembalian WAIT_IO_COMPLETION.

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

Jika ReadFileEx mencoba membaca melewati end-of-file (EOF), panggilan ke GetOverlappedResult untuk operasi tersebut mengembalikan FALSE dan GetLastError mengembalikan ERROR_HANDLE_EOF.

Keterangan

Saat menggunakan ReadFileEx , 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 ReadFileEx 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 ReadFileEx 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 baca yang ditentukan dalam panggilan ke ReadFileEx tumpang tindih dengan bagian terkunci, panggilan ke ReadFileEx gagal.

Saat mencoba membaca data dari mailslot yang buffer-nya terlalu kecil, ReadFileEx mengembalikan FALSE, dan GetLastError mengembalikan ERROR_INSUFFICIENT_BUFFER.

Mengakses buffer input saat operasi baca menggunakan buffer dapat menyebabkan kerusakan data yang dibaca ke dalam buffer tersebut. Aplikasi tidak boleh membaca dari, menulis ke, mengalokasikan ulang, atau membebaskan buffer input yang digunakan operasi baca hingga operasi baca selesai.

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

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 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. Untuk informasi tambahan, lihat Tentang NTFS Transaksional.

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