Fungsi NtReadFile (ntifs.h)
Rutinitas NtReadFile membaca data dari file yang terbuka.
Sintaks
__kernel_entry NTSYSCALLAPI NTSTATUS NtReadFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[out] PVOID Buffer,
[in] ULONG Length,
[in, optional] PLARGE_INTEGER ByteOffset,
[in, optional] PULONG Key
);
Parameter
[in] FileHandle
Tangani ke objek file. Handel ini dibuat oleh panggilan yang berhasil ke NtCreateFile atau NtOpenFile.
[in, optional] Event
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.
[in, optional] ApcRoutine
Parameter ini dicadangkan. Perangkat dan driver perantara harus mengatur penunjuk ini ke NULL.
[in, optional] ApcContext
Parameter ini dicadangkan. Perangkat dan driver perantara harus mengatur penunjuk ini ke NULL.
[out] IoStatusBlock
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.
[out] Buffer
Penunjuk ke buffer yang dialokasikan pemanggil yang menerima data yang dibaca dari file.
[in] Length
Ukuran, dalam byte, dari buffer yang ditujukkan oleh Buffer.
[in, optional] ByteOffset
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.
[in, optional] Key
Perangkat dan driver perantara harus mengatur penunjuk ini ke NULL.
Nilai kembali
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.
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.
Jika panggilan ke fungsi ini terjadi dalam mode pengguna, Anda harus menggunakan nama "NtReadFile" alih-alih "ZwReadFile".
Untuk panggilan dari driver mode kernel, versi NtXxx dan ZwXxx dari rutinItas Windows Native System Services dapat berperilaku berbeda dalam cara mereka menangani dan menginterpretasikan parameter input. Untuk informasi selengkapnya tentang hubungan antara versi NtXxx dan ZwXxx dari rutinitas, lihat Menggunakan Versi Nt dan Zw dari Rutinitas Layanan Sistem Asli.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 2000 |
| Target Platform | Universal |
| Header | ntifs.h (termasuk Wdm.h, Ntddk.h, Ntifs.h) |
| Pustaka | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (lihat bagian Keterangan) |
| Aturan kepatuhan DDI | BufAfterReqCompletedIntIoctlA, BufAfterReqCompletedIoctlA, BufAfterReqCompletedReadA, BufAfterReqCompletedWriteA, HwStorPortProhibitedDDIs, PowerIrpDDis |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk