Fungsi NtReadFile

Membaca data dari file yang terbuka.

Fungsi ini adalah mode pengguna yang setara dengan fungsi ZwReadFile yang didokumenkan dalam Windows Driver Kit (WDK).

Sintaks

NTSTATUS NtReadFile(
  _In_     HANDLE           FileHandle,
  _In_opt_ HANDLE           Event,
  _In_opt_ PIO_APC_ROUTINE  ApcRoutine,
  _In_opt_ PVOID            ApcContext,
  _Out_    PIO_STATUS_BLOCK IoStatusBlock,
  _Out_    PVOID            Buffer,
  _In_     ULONG            Length,
  _In_opt_ PLARGE_INTEGER   ByteOffset,
  _In_opt_ PULONG           Key
);

Parameter

FileHandle [in]

Tangani ke objek file. Handel ini dibuat oleh panggilan yang berhasil ke NtCreateFile atau NtOpenFile.

Peristiwa [in, opsional]

Secara opsional, handel ke objek peristiwa untuk diatur ke status bersinyali setelah operasi baca selesai. Perangkat dan driver perantara harus mengatur parameter ini ke NULL.

ApcRoutine [in, opsional]

Parameter ini dicadangkan. Perangkat dan driver perantara harus mengatur penunjuk ini ke NULL.

ApcContext [in, opsional]

Parameter ini dicadangkan. Perangkat dan driver perantara harus mengatur penunjuk ini ke NULL.

IoStatusBlock [out]

Arahkan ke struktur IO_STATUS_BLOCK yang menerima status penyelesaian akhir dan informasi tentang operasi baca yang diminta. Anggota Informasi menerima jumlah byte yang benar-benar dibaca dari file.

Buffer [out]

Penunjuk ke buffer yang dialokasikan pemanggil yang menerima data yang dibaca dari file.

Panjang [in]

Ukuran, dalam byte, dari buffer yang ditujukkan oleh Buffer.

ByteOffset [in, opsional]

Penunjuk ke variabel yang menentukan offset byte awal dalam file tempat operasi baca akan dimulai. Jika upaya dilakukan untuk membaca di luar akhir file, NtReadFile mengembalikan kesalahan.

Jika panggilan ke NtCreateFile mengatur salah satu bendera CreateOptions FILE_SYNCHRONOUS_IO_ALERT atau FILE_SYNCHRONOUS_IO_NONALERT, Manajer I/O mempertahankan posisi file saat ini. Jika demikian, pemanggil NtReadFile dapat menentukan bahwa offset posisi file saat ini digunakan alih-alih nilai ByteOffset eksplisit. Spesifikasi ini dapat dibuat dengan menggunakan salah satu metode berikut:

• Tentukan penunjuk ke nilai LARGE_INTEGER dengan anggota HighPart diatur ke -1 dan anggota LowPart diatur ke nilai yang ditentukan sistem FILE_USE_FILE_POINTER_POSITION.

• Berikan penunjuk NULL untuk ByteOffset.

NtReadFile memperbarui posisi file saat ini dengan menambahkan jumlah byte yang dibaca ketika menyelesaikan operasi baca, jika menggunakan posisi file saat ini yang dikelola oleh Manajer I/O.

Bahkan ketika Manajer I/O mempertahankan posisi file saat ini, pemanggil dapat mengatur ulang posisi ini dengan meneruskan nilai ByteOffset eksplisit ke NtReadFile. Melakukan ini secara otomatis mengubah posisi file saat ini ke nilai ByteOffset tersebut, melakukan operasi baca, lalu memperbarui posisi sesuai dengan jumlah byte yang benar-benar dibaca. Teknik ini memberikan layanan pencarian dan baca atom pemanggil.

Kunci [in, opsional]

Perangkat dan driver perantara harus mengatur penunjuk ini ke NULL.

Menampilkan nilai

NtReadFile mengembalikan kode kesalahan STATUS_SUCCESS atau NTSTATUS yang sesuai.

Keterangan

Penelepon NtReadFile harus sudah memanggil NtCreateFile dengan nilai FILE_READ_DATA atau GENERIC_READ yang ditetapkan dalam parameter DesiredAccess .

Jika panggilan sebelumnya ke NtCreateFile mengatur bendera FILE_NO_INTERMEDIATE_BUFFERING dalam parameter CreateOptions ke NtCreateFile, parameter Length dan ByteOffset ke NtReadFile harus kelipatan ukuran sektor. Untuk informasi selengkapnya, lihat NtCreateFile.

NtReadFile mulai membaca dari ByteOffset yang diberikan atau posisi file saat ini ke dalam Buffer yang diberikan. Ini mengakhiri operasi baca di bawah salah satu kondisi berikut:

• Buffer penuh karena jumlah byte yang ditentukan oleh parameter Panjang telah dibaca. Oleh karena itu, tidak ada lagi data yang dapat ditempatkan ke dalam buffer tanpa luapan.

• Akhir file tercapai selama operasi baca, sehingga tidak ada lagi data dalam file yang akan ditransfer ke buffer.

Jika pemanggil membuka file dengan bendera SYNCHRONIZE yang diatur di DesiredAccess, alur panggilan dapat disinkronkan ke penyelesaian operasi baca dengan menunggu handel file, FileHandle. Handel disinyalir setiap kali operasi I/O yang dikeluarkan pada handel selesai. Namun, pemanggil tidak boleh menunggu handel yang dibuka untuk akses file sinkron (FILE_SYNCHRONOUS_IO_NONALERT atau FILE_SYNCHRONOUS_IO_ALERT). Dalam hal ini, NtReadFile menunggu atas nama pemanggil dan tidak kembali sampai operasi baca selesai. Pemanggil dapat dengan aman menunggu handel file hanya jika ketiga kondisi berikut terpenuhi:

• Handel dibuka untuk akses asinkron (yaitu, tidak ada bendera FILE_SYNCHRONOUS_IO_XXX yang ditentukan).

• Handel hanya digunakan untuk satu operasi I/O pada satu waktu.

• NtReadFile mengembalikan STATUS_PENDING.

Driver harus memanggil NtReadFile dalam konteks proses sistem jika ada salah satu kondisi berikut:

• Driver membuat handel file yang diteruskannya ke NtReadFile.

• NtReadFile akan memberi tahu driver tentang penyelesaian I/O melalui peristiwa yang dibuat driver.

• NtReadFile akan memberi tahu driver penyelesaian I/O dengan cara rutin panggilan balik APC yang diteruskan driver ke NtReadFile.

Handel file dan peristiwa hanya valid dalam konteks proses tempat handel dibuat. Oleh karena itu, untuk menghindari lubang keamanan, driver harus membuat file atau handel peristiwa apa pun yang diteruskannya ke NtReadFile dalam konteks proses sistem daripada konteks proses tempat driver berada.

Demikian juga, NtReadFile harus dipanggil dalam konteks proses sistem jika memberi tahu driver penyelesaian I/O melalui APC, karena APC selalu ditembakkan dalam konteks utas yang mengeluarkan permintaan I/O. Jika driver memanggil NtReadFile dalam konteks proses selain sistem, APC dapat tertunda tanpa batas waktu, atau mungkin tidak diaktifkan sama sekali.

Untuk informasi selengkapnya tentang bekerja dengan file, lihat Menggunakan File di Driver.

Penelepon NtReadFile harus berjalan di IRQL = PASSIVE_LEVEL dan dengan APC kernel khusus diaktifkan.

Persyaratan

Lihat juga

KeInitializeEvent

NtCreateFile

NtQueryInformationFile

NtSetInformationFile

NtWriteFile