Fungsi FltReadFileEx (fltkernel.h)
FltReadFileEx membaca data dari file, streaming, atau perangkat yang terbuka. Fungsi ini memperluas FltReadFile untuk memungkinkan penggunaan opsional MDL untuk membaca data alih-alih alamat buffer yang dipetakan.
Sintaks
NTSTATUS FLTAPI FltReadFileEx(
[in] PFLT_INSTANCE InitiatingInstance,
[in] PFILE_OBJECT FileObject,
[in, optional] PLARGE_INTEGER ByteOffset,
[in] ULONG Length,
[out] PVOID Buffer,
[in] FLT_IO_OPERATION_FLAGS Flags,
[out, optional] PULONG BytesRead,
[in, optional] PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
[in, optional] PVOID CallbackContext,
[in, optional] PULONG Key,
[in, optional] PMDL Mdl
);
Parameter
[in] InitiatingInstance
Penunjuk instans buram untuk instans driver minifilter tempat operasi akan dikirim. Instans harus dilampirkan ke volume tempat file berada. Parameter ini diperlukan dan tidak boleh NULL.
[in] FileObject
Penunjuk ke FILE_OBJECT untuk file tempat data akan dibaca. Objek file ini harus dibuka saat ini. Memanggil FltReadFileEx ketika objek file belum terbuka atau tidak lagi terbuka (misalnya, dalam rutinitas panggilan balik pra-buat atau pasca-pembersihan) menyebabkan sistem menegaskan pada build yang diperiksa. Parameter ini diperlukan dan tidak boleh NULL.
[in, optional] ByteOffset
Penunjuk ke variabel yang dialokasikan pemanggil yang menentukan offset byte awal dalam file tempat operasi baca akan dimulai.
Jika ByteOffset ditentukan, I/O dilakukan pada offset tersebut, terlepas dari nilai saat ini dari bidang CurrentByteOffset objek file.
- Jika file dibuka untuk I/O sinkron (FO_SYNCHRONOUS_IO diatur dalam bidang Bendera objek file), pemanggil dapat mengatur ByteOffset-LowPart> ke FILE_USE_FILE_POINTER_POSITION dan ByteOffset-HighPart> ke -1 agar I/O dilakukan di bidang CurrentByteOffset objek file.
- Jika file tidak dibuka untuk I/O sinkron, menggunakan FILE_USE_FILE_POINTER_POSITION adalah kesalahan.
Jika ByteOffset tidak ditentukan:
- Jika file tidak dibuka untuk I/O sinkron, itu adalah kesalahan.
- Jika tidak, I/O dilakukan di CurrentByteOffset objek file.
Jika objek file dibuka untuk I/O sinkron, bidang CurrentByteOffset akan diperbarui kecuali penelepon melewati bendera FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET.
- Catatan: sistem file masih memperbarui CurrentByteOffset dalam hal ini. Manajer Filter menyimpan nilai CurrentByteOffset sebelum mengirim I/O ke bawah tumpukan dan memulihkannya saat I/O kembali. Dari perspektif pemanggil FltReadFileEx (dan filter pada ketinggian yang lebih tinggi) CurrrentByteOffset tidak diperbarui. Tetapi filter di bawah pemanggil melihat nilai CurrentByteOffset yang diperbarui dalam panggilan balik pasca-baca/tulis mereka.
Jika objek file tidak dibuka untuk I/O sinkron, bidang CurrentByteOffset tidak diperbarui terlepas dari status parameter ByteOffset .
[in] Length
Ukuran, dalam byte, dari buffer yang dirujuk parameter Buffer .
[out] Buffer
Penunjuk ke buffer yang dialokasikan pemanggil yang menerima data yang dibaca dari file. Jika MDL disediakan dalam Mdl, Buffer harus NULL.
[in] Flags
Bitmask bendera yang menentukan jenis operasi baca yang akan dilakukan.
Bendera | Makna |
---|---|
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET | Driver minifilter dapat mengatur bendera ini untuk menentukan bahwa FltReadFile tidak boleh memperbarui bidang CurrentByteOffset objek file. |
FLTFL_IO_OPERATION_NON_CACHED | Driver minifilter dapat mengatur bendera ini untuk menentukan bacaan yang tidak di-cache, meskipun objek file tidak dibuka dengan FILE_NO_INTERMEDIATE_BUFFERING. |
FLTFL_IO_OPERATION_PAGING | Driver minifilter dapat mengatur bendera ini untuk menentukan pembacaan halaman. |
FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING | Driver minifilter dapat mengatur bendera ini untuk menentukan pembacaan I/O halaman sinkron. Driver minifilter yang mengatur bendera ini juga harus mengatur bendera FLTFL_IO_OPERATION_PAGING. Tersedia mulai dari Windows Vista. |
[out, optional] BytesRead
Penunjuk ke variabel yang dialokasikan pemanggil yang menerima jumlah byte yang dibaca dari file. Jika CallbackRoutine bukan NULL, parameter ini diabaikan. Jika tidak, parameter ini bersifat opsional dan dapat berupa NULL.
[in, optional] CallbackRoutine
Arahkan ke rutinitas panggilan balik yang ditik PFLT_COMPLETED_ASYNC_IO_CALLBACK untuk memanggil saat operasi baca selesai. Parameter ini bersifat opsional dan dapat berupa NULL.
[in, optional] CallbackContext
Penunjuk konteks yang akan diteruskan ke CallbackRoutine jika ada. Parameter ini bersifat opsional dan dapat berupa NULL. Jika CallbackRoutine NULL, parameter ini diabaikan.
[in, optional] Key
Kunci opsional yang terkait dengan kunci rentang byte.
[in, optional] Mdl
MDL opsional yang menjelaskan memori tempat data dibaca. Jika buffer disediakan dalam Buffer , maka Mdl harus NULL.
Mengembalikan nilai
FltReadFileEx mengembalikan nilai NTSTATUS yang dikembalikan oleh sistem file.
Keterangan
Driver minifilter memanggil FltReadFileEx untuk membaca data dari file yang terbuka.
FltReadFileEx membuat permintaan baca dan mengirimkannya ke instans driver minifilter yang terpasang di bawah instans yang memulai, dan ke sistem file. Instans yang ditentukan dan instans yang terpasang di atasnya tidak menerima permintaan baca.
FltReadFileEx melakukan I/O non-cache jika salah satu hal berikut ini benar:
Pemanggil mengatur bendera FLTFL_IO_OPERATION_NON_CACHED di parameter Bendera .
Objek file dibuka untuk I/O yang tidak di-cache. Biasanya, ini dilakukan dengan menentukan bendera FILE_NO_INTERMEDIATE_BUFFERING CreateOptions dalam panggilan sebelumnya ke FltCreateFile, FltCreateFileEx, atau ZwCreateFile.
I/O non-cache memberlakukan batasan berikut pada nilai parameter yang diteruskan ke FltReadFileEx:
Buffer yang ditunjukkan parameter Buffer harus diselaraskan sesuai dengan persyaratan penyelarasan perangkat penyimpanan yang mendasar. Untuk mengalokasikan buffer yang selaras seperti itu, panggil FltAllocatePoolAlignedWithTag.
Offset byte yang ditujukan parameter ByteOffset harus menjadi kelipatan nonnegatif dari ukuran sektor volume.
Panjang yang ditentukan dalam parameter Panjang harus merupakan kelipatan nonnegatif dari ukuran sektor volume.
Jika upaya dilakukan untuk membaca di luar akhir file, FltReadFileEx mengembalikan kesalahan.
Jika nilai parameter CallbackRoutine bukan NULL, operasi baca dilakukan secara asinkron.
Jika nilai parameter CallbackRoutine adalah NULL, operasi baca dilakukan secara sinkron. Artinya, FltReadFileEx menunggu sampai operasi baca selesai sebelum kembali. Ini benar bahkan jika objek file yang dituju FileObject dibuka untuk I/O asinkron.
Jika beberapa utas memanggil FltReadFileEx untuk objek file yang sama, dan objek file dibuka untuk I/O sinkron, manajer filter tidak mencoba menserialisasikan I/O pada file. Dalam hal ini, FltReadFileEx berbeda dari ZwReadFile.
Parameter Mdl disediakan sebagai kenyamanan ketika minifilter sudah memiliki MDL yang tersedia. MDL digunakan secara langsung dan langkah tambahan pemetaan alamat untuk Buffer dapat dihindari.
Persyaratan
Persyaratan | Nilai |
---|---|
Klien minimum yang didukung | Windows 8 |
Target Platform | Universal |
Header | fltkernel.h (termasuk Fltkernel.h) |
Pustaka | FltMgr.lib |
DLL | Fltmgr.sys |
IRQL | PASSIVE_LEVEL |