Fungsi ZwReadFile (wdm.h)
Rutinitas ZwReadFile membaca data dari file yang terbuka.
Sintaks
NTSYSAPI NTSTATUS ZwReadFile(
[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 ZwCreateFile atau ZwOpenFile.
[in, optional] Event
Secara opsional, handel ke objek peristiwa untuk diatur ke status yang disinyalkan setelah operasi baca selesai. Driver perangkat dan 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 penelepon yang menerima data yang dibaca dari file.
[in] Length
Ukuran, dalam byte, dari buffer yang diacu 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, ZwReadFile mengembalikan kesalahan.
Jika panggilan ke ZwCreateFile 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 ZwReadFile 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.
ZwReadFile 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 ZwReadFile. 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 penelepon.
[in, optional] Key
Perangkat dan driver perantara harus mengatur penunjuk ini ke NULL.
Nilai kembali
ZwReadFile mengembalikan kode kesalahan STATUS_SUCCESS atau NTSTATUS yang sesuai.
Keterangan
Pemanggil ZwReadFile harus sudah memanggil ZwCreateFile dengan nilai FILE_READ_DATA atau GENERIC_READ yang ditetapkan dalam parameter DesiredAccess .
Jika panggilan sebelumnya ke ZwCreateFile mengatur bendera FILE_NO_INTERMEDIATE_BUFFERING dalam parameter CreateOptions ke ZwCreateFile, parameter Length dan ByteOffset ke ZwReadFile harus kelipatan ukuran sektor. Untuk informasi selengkapnya, lihat ZwCreateFile.
ZwReadFile 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, utas 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, ZwReadFile 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 (artinya, tidak ada bendera FILE_SYNCHRONOUS_IO_XXX yang ditentukan).
Handel hanya digunakan untuk satu operasi I/O pada satu waktu.
ZwReadFile mengembalikan STATUS_PENDING.
Driver harus memanggil ZwReadFile dalam konteks proses sistem jika ada salah satu kondisi berikut:
Driver membuat handel file yang diteruskannya ke ZwReadFile.
ZwReadFile akan memberi tahu driver penyelesaian I/O melalui peristiwa yang dibuat driver.
ZwReadFile akan memberi tahu driver penyelesaian I/O dengan rutinitas panggilan balik APC yang diteruskan driver ke ZwReadFile.
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 ZwReadFile dalam konteks proses sistem daripada konteks proses tempat driver berada.
Demikian juga, ZwReadFile 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 ZwReadFile dalam konteks proses selain sistem, APC dapat ditunda tanpa batas waktu, atau mungkin tidak diaktifkan sama sekali.
Untuk informasi selengkapnya tentang bekerja dengan file, lihat Menggunakan File di Driver.
Pemanggil ZwReadFile 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".
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Target Platform | Universal |
| Header | wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h) |
| Pustaka | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (lihat bagian Keterangan) |
| Aturan kepatuhan DDI | BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWriteA(kmdf), HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |