Fungsi ReadFile (fileapi.h)

Artikel
03/14/2023

Membaca data dari perangkat file atau input/output (I/O) yang ditentukan. Pembacaan terjadi pada posisi yang ditentukan oleh penunjuk file jika didukung oleh perangkat.

Fungsi ini dirancang untuk operasi sinkron dan asinkron. Untuk fungsi serupa yang dirancang hanya untuk operasi asinkron, lihat ReadFileEx.

Sintaks

BOOL ReadFile(
  [in]                HANDLE       hFile,
  [out]               LPVOID       lpBuffer,
  [in]                DWORD        nNumberOfBytesToRead,
  [out, optional]     LPDWORD      lpNumberOfBytesRead,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Parameter

[in] hFile

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

Parameter hFile harus dibuat dengan akses baca. Untuk informasi selengkapnya, lihat Hak Akses Generik dan Keamanan File dan Hak Akses.

Untuk operasi baca asinkron, hFile dapat menjadi handel apa pun yang dibuka dengan bendera FILE_FLAG_OVERLAPPED oleh fungsi CreateFile , atau handel soket yang dikembalikan oleh soket atau fungsi terima .

[out] lpBuffer

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

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

[in] nNumberOfBytesToRead

Jumlah maksimum byte yang akan dibaca.

[out, optional] lpNumberOfBytesRead

Penunjuk ke variabel yang menerima jumlah byte yang dibaca saat menggunakan parameter hFile sinkron. ReadFile menetapkan nilai ini ke nol sebelum melakukan pemeriksaan kesalahan atau pekerjaan apa pun. Gunakan NULL untuk parameter ini jika ini adalah operasi asinkron untuk menghindari hasil yang berpotensi salah.

Parameter ini hanya dapat null ketika parameter lpOverlapped bukan NULL.

Windows 7: Parameter ini tidak boleh NULL.

Untuk informasi lebih lanjut, lihat bagian Keterangan.

[in, out, optional] lpOverlapped

Penunjuk ke struktur TUMPANG TINDIH diperlukan jika parameter hFile dibuka dengan FILE_FLAG_OVERLAPPED, jika tidak, itu bisa NULL.

Jika hFile dibuka dengan FILE_FLAG_OVERLAPPED, parameter lpOverlapped harus menunjuk ke struktur TUMPANG TINDIH yang valid dan unik, jika tidak, fungsi dapat salah melaporkan bahwa operasi baca selesai.

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

Untuk informasi selengkapnya tentang kombinasi lpOverlapped dan FILE_FLAG_OVERLAPPED yang berbeda, lihat bagian Keterangan dan bagian Sinkronisasi dan Posisi File .

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol (TRUE).

Jika fungsi gagal, atau menyelesaikan secara asinkron, nilai yang dikembalikan adalah nol (FALSE). Untuk mendapatkan informasi kesalahan yang diperluas, panggil fungsi GetLastError .

Catatan Kode GetLastErrorERROR_IO_PENDING bukanlah kegagalan; ini menunjuk operasi baca tertunda penyelesaiannya secara asinkron. Untuk informasi selengkapnya, lihat Keterangan.

Keterangan

Fungsi ReadFile kembali ketika salah satu kondisi berikut terjadi:

Jumlah byte yang diminta dibaca.
Operasi tulis selesai pada akhir tulis pipa.
Handel asinkron sedang digunakan dan pembacaan terjadi secara asinkron.
Muncul kesalahan.

Fungsi ReadFile mungkin gagal dengan ERROR_INVALID_USER_BUFFER atau ERROR_NOT_ENOUGH_MEMORY setiap kali ada terlalu banyak permintaan I/O asinkron yang luar biasa.

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.

Fungsi ReadFile mungkin gagal dengan ERROR_NOT_ENOUGH_QUOTA, yang berarti buffer proses panggilan tidak dapat dikunci halaman. Untuk informasi tambahan, lihat SetProcessWorkingSetSize.

Jika bagian dari file dikunci oleh proses lain dan operasi baca tumpang tindih dengan bagian terkunci, fungsi ini gagal.

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. Ini bisa sangat bermasalah saat menggunakan handel file asinkron. Informasi tambahan mengenai handel file sinkron versus asinkron dapat ditemukan di bagian Sinkronisasi dan Posisi File dan di topik referensi CreateFile .

Karakter dapat dibaca dari buffer input konsol dengan menggunakan ReadFile dengan handel ke input konsol. Mode konsol menentukan perilaku yang tepat dari fungsi ReadFile . Secara default, mode konsol ENABLE_LINE_INPUT, yang menunjukkan bahwa ReadFile harus membaca hingga mencapai pengembalian pengangkutan. Jika Anda menekan Ctrl+C, panggilan berhasil, tetapi GetLastError mengembalikan ERROR_OPERATION_ABORTED. Untuk informasi selengkapnya, lihat CreateFile.

Saat membaca dari perangkat komunikasi, perilaku ReadFile ditentukan oleh batas waktu komunikasi saat ini sebagaimana diatur dan diambil dengan menggunakan fungsi SetCommTimeouts dan GetCommTimeouts . Hasil yang tidak dapat diprediksi dapat terjadi jika Anda gagal mengatur nilai waktu habis. Untuk informasi selengkapnya tentang batas waktu komunikasi, lihat COMMTIMEOUTS.

Jika ReadFile mencoba membaca dari mailslot yang memiliki buffer yang terlalu kecil, fungsi mengembalikan FALSE dan GetLastError mengembalikan ERROR_INSUFFICIENT_BUFFER.

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

Jika hFile dibuka dengan FILE_FLAG_OVERLAPPED, kondisi berikut berlaku:

Parameter lpOverlapped harus menunjuk ke struktur TUMPANG TINDIH yang valid dan unik, jika tidak, fungsi dapat salah melaporkan bahwa operasi baca selesai.
Parameter lpNumberOfBytesRead harus diatur ke NULL. Gunakan fungsi GetOverlappedResult untuk mendapatkan jumlah byte aktual yang dibaca. Jika parameter hFile dikaitkan dengan port penyelesaian I/O, Anda juga bisa mendapatkan jumlah byte yang dibaca dengan memanggil fungsi GetQueuedCompletionStatus .

Sinkronisasi dan Posisi File

Jika hFile dibuka dengan FILE_FLAG_OVERLAPPED, hFile adalah handel file asinkron; jika tidak, itu sinkron. Aturan untuk menggunakan struktur TUMPANG TINDIH sedikit berbeda untuk masing-masing, seperti yang disebutkan sebelumnya.

Catatan Jika file atau perangkat dibuka untuk I/O asinkron, panggilan berikutnya ke fungsi seperti ReadFile menggunakan handel tersebut umumnya segera kembali, tetapi juga dapat berperilaku sinkron sehubungan dengan eksekusi yang diblokir. Untuk informasi selengkapnya, lihat http://support.microsoft.com/kb/156932.

Pertimbangan untuk bekerja dengan handel file asinkron:

ReadFile dapat kembali sebelum operasi baca selesai. Dalam skenario ini, ReadFile mengembalikan FALSE dan fungsi GetLastError mengembalikan ERROR_IO_PENDING, yang memungkinkan proses panggilan berlanjut saat sistem menyelesaikan operasi baca.
Parameter lpOverlapped tidak boleh NULL dan harus digunakan dengan ingat fakta berikut:
- Meskipun peristiwa yang ditentukan dalam struktur TUMPANG TINDIH diatur dan diatur ulang secara otomatis oleh sistem, offset yang ditentukan dalam struktur TUMPANG TINDIH tidak diperbarui secara otomatis.
- ReadFile mengatur ulang peristiwa ke status tidak bertanda saat memulai operasi I/O.
- Peristiwa yang ditentukan dalam struktur TUMPANG TINDIH diatur ke status bersinyali ketika operasi baca selesai; hingga saat itu, operasi baca dianggap tertunda.
- Karena operasi baca dimulai pada offset yang ditentukan dalam struktur TUMPANG TINDIH , dan ReadFile dapat kembali sebelum operasi baca tingkat sistem selesai (baca tertunda), baik offset maupun bagian lain dari struktur harus dimodifikasi, dibebaskan, atau digunakan kembali oleh aplikasi sampai peristiwa disinyalkan (yaitu, baca selesai).
- Jika end-of-file (EOF) terdeteksi selama operasi asinkron, panggilan ke GetOverlappedResult untuk operasi tersebut mengembalikan FALSE dan GetLastError mengembalikan ERROR_HANDLE_EOF.

Pertimbangan untuk bekerja dengan handel file sinkron:

Jika lpOverlappedNULL, operasi baca dimulai pada posisi file saat ini dan ReadFile tidak kembali sampai operasi selesai, dan sistem memperbarui penunjuk file sebelum ReadFile kembali.
Jika lpOverlapped bukan NULL, operasi baca dimulai pada offset yang ditentukan dalam struktur TUMPANG TINDIH dan ReadFile tidak kembali sampai operasi baca selesai. Sistem memperbarui offset YANG TUMPANG TINDIH dan penunjuk file sebelum ReadFile kembali.
Jika lpOverlapped adalah NULL, maka ketika operasi baca sinkron mencapai akhir file, ReadFile mengembalikan TRUE dan diatur *lpNumberOfBytesRead ke nol.
Jika lpOverlapped bukan NULL, maka ketika operasi baca sinkron mencapai akhir file, ReadFile mengembalikan FALSE dan GetLastError mengembalikan ERROR_HANDLE_EOF.

Untuk informasi selengkapnya, lihat CreateFile dan I/O Sinkron dan Asinkron.

Pipa

Jika pipa anonim sedang digunakan dan handel tulis telah ditutup, ketika ReadFile mencoba membaca menggunakan handel baca yang sesuai dari pipa, fungsi mengembalikan FALSE dan GetLastError mengembalikan ERROR_BROKEN_PIPE.

Jika pipa bernama sedang dibaca dalam mode pesan dan pesan berikutnya lebih panjang dari parameter nNumberOfBytesToRead yang ditentukan, ReadFile mengembalikan FALSE dan GetLastError mengembalikan ERROR_MORE_DATA. Sisa pesan dapat dibaca dengan panggilan berikutnya ke fungsi ReadFile atau PeekNamedPipe .

Jika parameter lpNumberOfBytesRead nol saat ReadFile mengembalikan TRUE pada pipa, ujung pipa lainnya yang disebut fungsi WriteFile dengan nNumberOfBytesToWrite diatur ke nol.

Untuk informasi selengkapnya tentang pipa, lihat Pipa.

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 selengkapnya, lihat Tentang Transactional NTFS.

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

Contoh

Untuk contoh kode yang menunjukkan kepada Anda cara menguji akhir file, lihat Pengujian untuk Akhir File. Untuk contoh lain, lihat Membuat dan Menggunakan File Sementara dan Membuka File untuk Membaca atau Menulis.

Persyaratan


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