Fungsi FltWriteFileEx (fltkernel.h)

Artikel
11/16/2023

FltWriteFileEx digunakan untuk menulis data ke file, streaming, atau perangkat terbuka. Fungsi ini memperluas FltWriteFile untuk memungkinkan penggunaan opsional MDL untuk menulis data alih-alih alamat buffer yang dipetakan.

Sintaks

NTSTATUS FLTAPI FltWriteFileEx(
  [in]            PFLT_INSTANCE                    InitiatingInstance,
  [in]            PFILE_OBJECT                     FileObject,
  [in, optional]  PLARGE_INTEGER                   ByteOffset,
  [in]            ULONG                            Length,
  [in]            PVOID                            Buffer,
  [in]            FLT_IO_OPERATION_FLAGS           Flags,
  [out, optional] PULONG                           BytesWritten,
  [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 ditulis. Objek file ini harus dibuka saat ini. Memanggil FltWriteFileEx ketika objek file belum terbuka atau tidak lagi terbuka (misalnya, dalam rutinitas panggilan balik pra-buat atau pasca-pembersihan) menyebabkan sistem assert pada build yang diperiksa. Parameter ini diperlukan dan tidak boleh NULL.

[in, optional] ByteOffset

Penunjuk ke variabel yang dialokasikan penelepon 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 di 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.
Pemanggil dapat mengatur ByteOffset-LowPart> ke FILE_WRITE_TO_END_OF_FILE dan ByteOffset-HighPart> ke -1 untuk memulai penulisan di akhir file (yaitu, melakukan penulisan penambahan).

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 FltWriteFileEx (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 .

Jika objek file yang ditunjukkan FileObject dibuka untuk I/O asinkron, parameter ini diperlukan dan tidak boleh NULL.

FltWriteFileEx tidak mendukung bendera FILE_WRITE_TO_END_OF_FILE.

[in] Length

Ukuran, dalam byte, dari buffer yang dirujuk oleh parameter Buffer . Jika MDL disediakan dalam Mdl, panjang adalah ukuran data yang dijelaskan MDL.

[in] Buffer

Penunjuk ke buffer yang berisi data yang akan ditulis ke file. Jika file dibuka untuk I/O non-cache, buffer ini harus diselaraskan sesuai dengan persyaratan penyelarasan perangkat penyimpanan yang mendasarinya. Driver minifilter dapat mengalokasikan buffer yang selaras dengan memanggil FltAllocatePoolAlignedWithTag.

Jika MDL disediakan di Mdl, Buffer harus NULL.

[in] Flags

Bitmask bendera yang menentukan jenis operasi tulis yang akan dilakukan.

Bendera	Makna
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET	Driver minifilter dapat mengatur bendera ini untuk menentukan bahwa FltWriteFileEx tidak akan memperbarui bidang CurrentByteOffset objek file.
FLTFL_IO_OPERATION_NON_CACHED	Driver minifilter dapat mengatur bendera ini untuk menentukan tulisan 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 penulisan halaman.
FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING	Driver minifilter dapat mengatur bendera ini untuk menentukan penulisan I/O halaman sinkron. Driver minifilter yang mengatur bendera ini juga harus mengatur bendera FLTFL_IO_OPERATION_PAGING. Bendera ini tersedia dimulai dengan Windows Vista.

[out, optional] BytesWritten

Penunjuk ke variabel yang dialokasikan penelepon yang menerima jumlah byte yang ditulis ke file. Jika CallbackRoutine bukan NULL, parameter ini diabaikan. Jika tidak, parameter ini bersifat opsional dan dapat berupa NULL.

[in, optional] CallbackRoutine

Penunjuk ke rutinitas panggilan balik yang ditik PFLT_COMPLETED_ASYNC_IO_CALLBACK untuk memanggil saat operasi tulis selesai. Parameter ini bersifat opsional dan dapat berupa NULL.

[in, optional] CallbackContext

Penunjuk konteks yang akan diteruskan ke rutinitas di CallbackRoutine jika ada. Parameter ini bersifat opsional dan dapat berupa NULL. Jika CallbackRoutine adalah NULL, parameter ini diabaikan.

[in, optional] Key

Kunci opsional yang terkait dengan kunci objek file.

[in, optional] Mdl

MDL opsional yang menjelaskan data untuk ditulis. Jika buffer disediakan dalam Buffer, maka Mdl harus NULL.

Mengembalikan nilai

FltWriteFileEx mengembalikan nilai NTSTATUS yang dikembalikan oleh sistem file.

Keterangan

Driver minifilter memanggil FltWriteFileEx untuk menulis data ke file terbuka.

FltWriteFileEx menyebabkan permintaan tulis dikirim 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 tulis.

FltWriteFileEx melakukan I/O non-cache jika salah satu hal berikut ini benar:

Penelepon 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 yang tidak di-cache memberlakukan batasan berikut pada nilai parameter yang diteruskan ke FltWriteFileEx:

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 nilai parameter CallbackRoutine bukan NULL, operasi tulis dilakukan secara asinkron.

Jika nilai parameter CallbackRoutine adalah NULL, operasi tulis dilakukan secara sinkron. Artinya, FltWriteFileEx menunggu sampai operasi tulis selesai sebelum kembali. Ini benar bahkan jika objek file yang dituju fileObject dibuka untuk I/O asinkron.

Jika beberapa utas memanggil FltWriteFileEx untuk objek file yang sama, dan objek file dibuka untuk I/O sinkron, manajer filter tidak mencoba membuat serial I/O pada file. Dalam hal ini, FltWriteFileEx berbeda dari ZwWriteFile.

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