Bagikan melalui

Fungsi ReadFile (fileapi.h)

  • Artikel

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.

Sintaksis

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 menerima fungsi.

[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 hingga 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 dapat NULL hanya ketika parameter lpOverlapped tidak NULL.

Windows 7: Parameter ini tidak dapat NULL.

Untuk informasi selengkapnya, lihat bagian Keterangan.

[in, out, optional] lpOverlapped

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

Jika hFile dibuka dengan FILE_FLAG_OVERLAPPED, parameter lpOverlapped harus menunjuk ke struktur yang valid dan unik TUMPANG TINDIH, 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 Offset dan OffsetHigh anggota struktur TUMPANG TINDIH. Untuk hFile yang tidak mendukung offset byte, Offset dan OffsetHigh diabaikan.

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

Mengembalikan nilai

Jika fungsi berhasil, nilai pengembalian 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 .

Nota

 ERROR_IO_PENDING kode GetLastError bukanlah kegagalan; ini menunjuk operasi baca yang tertunda penyelesaiannya secara asinkron. Untuk informasi selengkapnya, lihat Keterangan.

Komentar

Fungsi ReadFile mengembalikan saat salah satu kondisi berikut terjadi:

  • Jumlah byte yang diminta dibaca.
  • Operasi tulis selesai pada akhir tulis pipa.
  • Handel asinkron sedang digunakan dan bacaan terjadi secara asinkron.
  • Terjadi 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 dibaca sampai 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 yang valid dan unik TUMPANG TINDIH, 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, itu adalah handel file asinkron; jika tidak, itu sinkron. Aturan untuk menggunakan struktur TUMPANG TINDIH sedikit berbeda untuk masing-masing, seperti yang disebutkan sebelumnya.

Nota

 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 I/O disk asinkron muncul sebagai sinkron di Windows.

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 yang tidak ditandatangani saat memulai operasi I/O.
    • Peristiwa yang ditentukan dalam struktur TUMPANG TINDIH diatur ke status yang disinyalir saat 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 disinyalir (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 lpOverlapped NULL, operasi baca dimulai pada posisi file saat ini dan ReadFile tidak kembali hingga operasi selesai, dan sistem memperbarui penunjuk file sebelum ReadFile kembali.
  • Jika lpOverlapped tidak null, operasi baca dimulai pada offset yang ditentukan dalam struktur TUMPANG TINDIH dan ReadFile tidak kembali sampai operasi baca selesai. Sistem memperbarui offset TUMPANG TINDIH dan penunjuk file sebelum ReadFile kembali.
  • Jika lpOverlapped NULL, maka ketika operasi baca sinkron mencapai akhir file, ReadFile mengembalikan TRUE dan menetapkan ke nol.
  • Jika lpOverlapped tidak 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 terkait 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 adalah nol ketika ReadFile mengembalikan TRUE pada pipa, ujung pipa lain yang disebut fungsi WriteFile dengan nNumberOfBytesToWrite diatur ke nol.

Untuk informasi selengkapnya tentang pipa, lihat Pipes.

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 TentangTransaksi NTFS .

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

Teknologi Didukung
Protokol Server Message Block (SMB) 3.0 Ya
Failover Transparan (TFO) SMB 3.0 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

Syarat Nilai
klien minimum yang didukung Windows XP [aplikasi desktop | Aplikasi UWP]
server minimum yang didukung Windows Server 2003 [aplikasi desktop | Aplikasi UWP]
Platform Target Windows
Header fileapi.h (termasuk Windows.h)
Pustaka Kernel32.lib
DLL Kernel32.dll

Lihat juga

CancelIo

CancelIoEx

CancelSynchronousIo

CreateFile

File Management Functions

GetCommTimeouts

GetOverlappedResult

GetQueuedCompletionStatus

TUMPANG TINDIH

PeekNamedPipe

ReadFileEx

SetCommTimeouts

SetErrorMode

WriteFile