Fungsi FltCreateFileEx2 (fltkernel.h)

Artikel
03/08/2023

Driver minifilter memanggil FltCreateFileEx2 untuk membuat file baru atau membuka file yang ada. Rutinitas ini mencakup parameter konteks buat opsional (ECP).

Sintaks

NTSTATUS FLTAPI FltCreateFileEx2(
  [in]            PFLT_FILTER               Filter,
  [in, optional]  PFLT_INSTANCE             Instance,
  [out]           PHANDLE                   FileHandle,
  [out, optional] PFILE_OBJECT              *FileObject,
  [in]            ACCESS_MASK               DesiredAccess,
  [in]            POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]           PIO_STATUS_BLOCK          IoStatusBlock,
  [in, optional]  PLARGE_INTEGER            AllocationSize,
  [in]            ULONG                     FileAttributes,
  [in]            ULONG                     ShareAccess,
  [in]            ULONG                     CreateDisposition,
  [in]            ULONG                     CreateOptions,
  [in, optional]  PVOID                     EaBuffer,
  [in]            ULONG                     EaLength,
  [in]            ULONG                     Flags,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Parameter

[in] Filter

Penunjuk filter buram untuk pemanggil.

[in, optional] Instance

Penunjuk instans buram untuk instans driver minifilter tempat permintaan pembuatan akan dikirim. Instans harus dilampirkan ke volume tempat file atau direktori berada. Parameter ini bersifat opsional dan dapat berupa NULL. Jika parameter ini NULL, permintaan dikirim ke objek perangkat di bagian atas tumpukan driver sistem file untuk volume. Jika parameter ini non-NULL, permintaan hanya dikirim ke instans driver minifilter yang dilampirkan di bawah instans yang ditentukan.

[out] FileHandle

Penunjuk ke variabel yang dialokasikan penelepon yang menerima handel file jika panggilan ke FltCreateFileEx2 berhasil.

[out, optional] FileObject

Penunjuk ke variabel yang dialokasikan penelepon yang menerima penunjuk objek file jika panggilan ke FltCreateFileEx2 berhasil. Parameter ini bersifat opsional dan dapat berupa NULL.

[in] DesiredAccess

Bitmask bendera yang menentukan jenis akses ke file atau direktori yang diperlukan pemanggil. Lihat parameter DesiredAccess dari IoCreateFileEx untuk informasi selengkapnya tentang parameter ini dan untuk daftar nilai bendera.

[in] ObjectAttributes

Penunjuk ke struktur OBJECT_ATTRIBUTES buram yang sudah diinisialisasi dengan InitializeObjectAttributes. Lihat parameter ObjectAttributesIoCreateFileEx untuk informasi selengkapnya dan untuk deskripsi setiap anggota struktur.

[out] IoStatusBlock

Arahkan ke struktur IO_STATUS_BLOCK yang menerima status penyelesaian akhir dan informasi tentang operasi yang diminta. Lihat parameter IoStatusBlock dari IoCreateFileEx untuk informasi selengkapnya tentang parameter ini.

[in, optional] AllocationSize

Secara opsional menentukan ukuran alokasi awal, dalam byte, untuk aliran file. Nilai bukan nol tidak berpengaruh kecuali file sedang dibuat, ditimpa, atau digantikan.

[in] FileAttributes

Menentukan satu atau beberapa bendera FILE_ATTRIBUTE_XXX , yang mewakili atribut file yang akan diatur jika Anda membuat, menggantikan, atau menimpa file. Lihat parameter FileAttributesIoCreateFileEx untuk detail selengkapnya dan untuk daftar bendera.

[in] ShareAccess

Menentukan jenis akses berbagi ke file yang diperlukan pemanggil, sebagai nol atau satu, atau kombinasi bendera. Lihat parameter ShareAccess dari IoCreateFileEx untuk detail selengkapnya dan untuk daftar bendera.

[in] CreateDisposition

Menentukan nilai yang menentukan tindakan yang akan diambil, bergantung pada apakah file sudah ada. Lihat parameter DisposisiIoCreateFileEx untuk daftar nilai yang mungkin.

[in] CreateOptions

Menentukan opsi yang akan diterapkan saat membuat atau membuka file. Parameter ini adalah kombinasi yang kompatibel dari bendera yang tercantum dan dijelaskan dalam parameter CreateOptions dari IoCreateFileEx.

[in, optional] EaBuffer

Penunjuk ke buffer FILE_FULL_EA_INFORMATION yang disediakan penelepon yang berisi informasi atribut yang diperluas (EA) untuk diterapkan ke file.

[in] EaLength

Panjang, dalam byte, dari EaBuffer.

[in] Flags

Menentukan opsi yang akan digunakan selama pembuatan permintaan pembuatan. Lihat parameter OpsiIoCreateFileEx untuk daftar opsi yang mungkin.

[in, optional] DriverContext

Penunjuk opsional ke struktur IO_DRIVER_CREATE_CONTEXT yang sudah diinisialisasi oleh IoInitializeDriverCreateContext.

Nilai kembali

FltCreateFileEx2 mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai. Lihat bagian Nilai Pengembaliandari IoCreateFileEx untuk daftar kemungkinan kode pengembalian.

Catatan

FltCreateFileEx2 mungkin mengembalikan STATUS_FILE_LOCK_CONFLICT sebagai nilai pengembalian atau di anggota Status struktur IO_STATUS_BLOCK yang diarahkan oleh parameter IoStatusBlock. Ini hanya akan terjadi jika file log NTFS penuh, dan kesalahan terjadi saat FltCreateFileEx2 mencoba menangani situasi ini.

Keterangan

FltCreateFileEx2 mirip dengan FltCreateFile dan FltCreateFileEx, kecuali mendukung parameter input DriverContext .

Untuk menentukan ECP sebagai bagian dari operasi pembuatan, inisialisasi anggota ExtraCreateParameter dari struktur IO_DRIVER_CREATE_CONTEXT dengan rutinitas FltAllocateExtraCreateParameterList . Jika ECP digunakan, EKP harus dibuat, dimanipulasi, dan dibebaskan menggunakan rutinitas yang sesuai.

Filter driver di bawah penelepon FltCreateFileEx2 tidak boleh menambahkan atau menghapus ECP pada pemanggil. Akibatnya, setelah kembali dari panggilan ke FltCreateFileEx2, daftar ECP harus tidak berubah dan dapat diteruskan ke panggilan tambahan FltCreateFileEx2 untuk operasi pembuatan lainnya. Perhatikan bahwa sistem operasi tidak secara otomatis membatalkan alokasi struktur daftar ECP - pemanggil FltCreateFileEx2 harus membatalkan alokasi struktur ini dengan memanggil rutinitas FltFreeExtraCreateParameterList .

Untuk membuat/membuka file dalam konteks transaksi, atur anggota TxnParameters dari struktur IO_DRIVER_CREATE_CONTEXT ke nilai yang dikembalikan oleh rutinitas IoGetTransactionParameterBlock .

FltCreateFileEx2 mengirimkan permintaan buat hanya ke instans yang terpasang di bawah instans driver minifilter yang ditentukan dan ke sistem file. Instans yang ditentukan dan instans yang terpasang di atasnya tidak menerima permintaan buat. Jika tidak ada instans yang ditentukan, permintaan masuk ke bagian atas tumpukan dan diterima oleh semua instans dan sistem file.

Ada dua cara alternatif untuk menentukan nama file yang akan dibuat atau dibuka dengan FltCreateFileEx2:

Sebagai nama jalur yang sepenuhnya memenuhi syarat, disediakan di anggota ObjectName dari objectAttributes input.
Sebagai nama jalur yang relatif terhadap file direktori yang diwakili oleh handel di anggota RootDirectory dari input ObjectAttributes.

FileHandle apa pun yang diperoleh dari FltCreateFileEx2 akhirnya harus dirilis dengan memanggil FltClose. Selain itu, setiap penunjuk FileObject yang dikembalikan harus didereferensikan ketika tidak lagi diperlukan dengan memanggil ObDereferenceObject.

Rutinitas driver yang tidak berjalan dalam konteks proses sistem harus mengatur atribut OBJ_KERNEL_HANDLE untuk parameter ObjectAttributes dari FltCreateFileEx2. Pengaturan atribut ini membatasi penggunaan handel yang dikembalikan oleh FltCreateFileEx2 ke proses yang berjalan dalam mode kernel. Jika tidak, handel dapat diakses oleh proses dalam konteks driver yang berjalan.

Catatan

Jangan panggil rutinitas ini dengan nilai IRP tingkat atas non-NULL, karena ini dapat menyebabkan kebuntuan sistem.

Bendera DesiredAccess tertentu dan kombinasi bendera memiliki efek berikut:

Agar penelepon menyinkronkan penyelesaian I/O dengan menunggu FileHandle yang dikembalikan diatur ke status Sinyal, bendera SYNCHRONIZE harus diatur.
Jika hanya bendera FILE_APPEND_DATA dan SYNCHRONIZE yang diatur, pemanggil hanya dapat menulis ke akhir file, dan informasi offset apa pun tentang permintaan tulis ke file diabaikan. Namun, file secara otomatis diperluas seperlunya untuk jenis operasi tulis ini.
Mengatur bendera FILE_WRITE_DATA untuk file juga memungkinkan permintaan tulis di luar akhir file terjadi. File secara otomatis diperluas untuk jenis permintaan tulis ini.
Jika hanya bendera FILE_EXECUTE dan SYNCHRONIZE yang diatur, pemanggil tidak dapat menggunakan handel yang dikembalikan dalam parameter FileHandle untuk langsung membaca atau menulis data apa pun ke atau dari file. Artinya, semua operasi pada file harus menggunakan I/O halaman sistem untuk membaca atau menulis data file.

Parameter ShareAccess menentukan apakah utas terpisah dapat mengakses file yang sama, mungkin secara bersamaan. Jika kedua pembuka file memiliki hak istimewa untuk mengakses file dengan cara yang ditentukan, file dapat berhasil dibuka dan dibagikan. Jika pemanggil asli FltCreateFileEx2 tidak menentukan FILE_SHARE_READ, FILE_SHARE_WRITE, atau FILE_SHARE_DELETE, tidak ada operasi terbuka lain yang dapat dilakukan pada file karena pemanggil asli diberikan akses eksklusif ke file.

Agar file bersama berhasil dibuka, DesiredAccess yang diminta ke file harus kompatibel dengan spesifikasi DesiredAccess dan ShareAccess dari semua permintaan terbuka sebelumnya yang belum dirilis dengan FltClose. Artinya, parameter DesiredAccess yang ditentukan ke FltCreateFileEx2 untuk file tertentu tidak boleh bertentangan dengan akses yang tidak diizinkan oleh pembuka file lain.

Catatan

Jika IO_IGNORE_SHARE_ACCESS_CHECK ditentukan dalam parameter Bendera , manajer I/O mengabaikan parameter ShareAccess . Namun, sistem file mungkin masih melakukan pemeriksaan akses. Dengan demikian, penting untuk menentukan mode berbagi yang Anda inginkan untuk parameter ShareAccess, bahkan saat menggunakan bendera IO_IGNORE_SHARE_ACCESS_CHECK. Selain itu, perhatikan bahwa ketika IO_IGNORE_SHARE_ACCESS_CHECK ditentukan, sistem file tidak melacak akses terbuka saat ini yang diinginkan atau akses bersama. Karena itu, panggilan terbuka berikutnya pada file yang sama mungkin berhasil.

Nilai CreateDisposition FILE_SUPERSEDE mengharuskan pemanggil memiliki akses DELETE ke objek file yang ada. Jika demikian, panggilan yang berhasil ke FltCreateFileEx2 dengan FILE_SUPERSEDE pada file yang ada secara efektif menghapus file tersebut dan kemudian membuatnya kembali. Ini menyiratkan bahwa jika file telah dibuka oleh utas lain, file akan dibuka dengan menentukan parameter ShareAccessdengan set bendera FILE_SHARE_DELETE. Perhatikan bahwa jenis disposisi ini konsisten dengan gaya POSIX menimpa file.

Nilai CreateDisposition FILE_OVERWRITE_IF dan FILE_SUPERSEDE serupa. Jika FltCreateFileEx2 dipanggil dengan file yang ada dan salah satu nilai CreateDisposition ini, file diganti.

Menimpa file secara semantik setara dengan operasi penggantian, kecuali untuk hal berikut:

Pemanggil harus memiliki akses tulis ke file, bukan menghapus akses. Ini menyiratkan bahwa, jika file telah dibuka oleh utas lain, file akan dibuka dengan bendera FILE_SHARE_WRITE yang diatur dalam parameter ShareAccess input.
Atribut file yang ditentukan dikombinasikan dengan atribut yang sudah diterapkan ke file dengan menggunakan operasi OR bitwise. Ini menyiratkan bahwa jika file telah dibuka oleh utas lain, penelepon berikutnya dari FltCreateFileEx2 tidak dapat menonaktifkan bendera FileAttributes yang ada tetapi dapat mengaktifkan bendera tambahan untuk file yang sama. Perhatikan bahwa gaya penimpaan file ini konsisten dengan MS-DOS, Windows 3.1, dan OS/2.

Nilai FILE_DIRECTORY_FILE CreateOptions menentukan bahwa file yang akan dibuat atau dibuka adalah file direktori. Ketika file direktori dibuat, sistem file membuat struktur yang sesuai pada disk untuk mewakili direktori kosong untuk struktur on-disk sistem file tertentu. Jika opsi ini ditentukan dan file yang diberikan untuk dibuka bukan file direktori atau jika pemanggil menentukan nilai CreateOptions atau CreateDisposition yang tidak konsisten, panggilan ke FltCreateFileEx2 gagal.

Bendera CreateOptions FILE_NO_INTERMEDIATE_BUFFERING mencegah sistem file melakukan buffer perantara atas nama pemanggil. Menentukan nilai ini menempatkan batasan tertentu pada parameter pemanggil ke Flt lainnya. Rutinitas file atau Zw.. Rutinitas file, termasuk yang berikut ini:

Setiap nilai offset byte yang diteruskan ke parameter ByteOffsetFltReadFile, ZwReadFile, FltWriteFile, atau ZwWriteFile harus merupakan kelipatan dari ukuran sektor.
Parameter Panjang yang diteruskan ke FltReadFile, ZwReadFile, FltWriteFile, atau ZwWriteFile harus kelipatan ukuran sektor. Perhatikan bahwa menentukan operasi baca ke buffer yang panjangnya persis dengan ukuran sektor dapat mengakibatkan lebih sedikit byte signifikan yang ditransfer ke buffer tersebut jika akhir file tercapai selama transfer.
Buffer harus diselaraskan sesuai dengan persyaratan penyelarasan perangkat penyimpanan yang mendasar. Informasi ini dapat diperoleh dengan memanggil FltCreateFileEx2 untuk mendapatkan handel untuk objek file yang mewakili perangkat fisik dan kemudian memanggil ZwQueryInformationFile dengan handel tersebut, menentukan FileAlignmentInformation sebagai nilai untuk parameter FileInformationClass . Untuk informasi selengkapnya tentang sistem FILE_XXX_ALIGNMENT nilai, yang ditentukan dalam Ntifs.h, lihat DEVICE_OBJECT dan Menginisialisasi Objek Perangkat.
Panggilan ke FltSetInformationFile atau ZwSetInformationFile dengan parameter FileInformationClass yang diatur ke FilePositionInformation harus menentukan offset yang merupakan kelipatan ukuran sektor.

Bendera CreateOptions FILE_SYNCHRONOUS_IO_ALERT dan FILE_SYNCHRONOUS_IO_NONALERT, yang saling eksklusif seperti namanya, tentukan bahwa file sedang dibuka untuk I/O sinkron. Ini berarti bahwa semua operasi I/O pada file harus sinkron selama terjadi melalui objek file yang dirujuk fileHandle yang dikembalikan. Semua I/O pada file tersebut diserialisasikan di semua utas dengan menggunakan handel yang dikembalikan. Dengan salah satu bendera CreateOptions ini diatur, Manajer I/O mempertahankan offset posisi file saat ini di bidang CurrentByteOffset objek file. Offset ini dapat digunakan dalam panggilan ke ZwReadFile dan ZwWriteFile. Ini juga dapat dikueri atau diatur dengan memanggil ZwQueryInformationFile atau ZwSetInformationFile.

Jika bendera CreateOptions FILE_OPEN_REPARSE_POINT tidak ditentukan dan FltCreateFileEx2 mencoba membuka file dengan titik reparse, pemrosesan titik pemilah ulang normal terjadi untuk file. Jika, di sisi lain, bendera FILE_OPEN_REPARSE_POINT ditentukan, pemrosesan reparse normal tidak terjadi dan FltCreateFileEx2 mencoba untuk langsung membuka file titik pemilah ulang. Dalam kedua kasus, jika operasi terbuka berhasil, FltCreateFileEx2 mengembalikan STATUS_SUCCESS; jika tidak, rutinitas mengembalikan kode kesalahan NTSTATUS. FltCreateFileEx2 tidak pernah mengembalikan STATUS_REPARSE.

Bendera CreateOptions FILE_OPEN_REQUIRING_OPLOCK menghilangkan waktu antara saat Anda membuka file dan meminta oplock yang berpotensi memungkinkan pihak ketiga untuk membuka file dan mendapatkan pelanggaran berbagi. Aplikasi dapat menggunakan bendera FILE_OPEN_REQUIRING_OPLOCK pada FltCreateFileEx2 dan kemudian meminta oplock apa pun. Ini memastikan bahwa pemilik oplock akan diberi tahu tentang permintaan terbuka nanti yang menyebabkan pelanggaran berbagi.

Di Windows 7, jika handel lain ada pada file ketika aplikasi menggunakan bendera FILE_OPEN_REQUIRING_OPLOCK, operasi pembuatan akan gagal dengan STATUS_OPLOCK_NOT_GRANTED. Pembatasan ini sudah tidak ada lagi dimulai dengan Windows 8.

Jika operasi pembuatan ini akan merusak oplock yang sudah ada pada file, maka mengatur bendera FILE_OPEN_REQUIRING_OPLOCK akan menyebabkan operasi pembuatan gagal dengan STATUS_CANNOT_BREAK_OPLOCK. Oplock yang ada tidak akan rusak oleh operasi pembuatan ini.

Aplikasi yang menggunakan bendera ini harus meminta oplock setelah panggilan ini berhasil, atau semua upaya selanjutnya untuk membuka file akan diblokir tanpa manfaat pemrosesan oplock yang khas. Demikian pula, jika panggilan ini berhasil tetapi permintaan oplock nanti gagal, aplikasi yang menggunakan bendera ini harus menutup handelnya setelah mendeteksi bahwa permintaan oplock telah gagal.

Catatan

Bendera FILE_OPEN_REQUIRING_OPLOCK tersedia di Windows 7, Windows Server 2008 R2 dan sistem operasi Windows yang lebih baru. Sistem file Microsoft yang mengimplementasikan bendera ini di Windows 7 adalah NTFS, FAT, dan exFAT.

Bendera CreateOptions FILE_RESERVE_OPFILTER memungkinkan aplikasi untuk meminta oplock tingkat 1, batch, atau filter untuk mencegah aplikasi lain mendapatkan pelanggaran berbagi. Namun, FILE_RESERVE_OPFILTER hanya praktis berguna untuk oplock filter. Untuk menggunakannya, Anda harus menyelesaikan langkah-langkah berikut:

Terbitkan permintaan buat dengan CreateOptions FILE_RESERVE_OPFILTER, DesiredAccess dari FILE_READ_ATTRIBUTES, dan ShareAccess yang tepat FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- Jika sudah ada handel terbuka, permintaan pembuatan gagal dengan STATUS_OPLOCK_NOT_GRANTED, dan oplock berikutnya yang diminta juga gagal.
- Jika Anda membuka dengan lebih banyak akses atau lebih sedikit berbagi juga akan menyebabkan kegagalan STATUS_OPLOCK_NOT_GRANTED.
Jika permintaan pembuatan berhasil, minta oplock.
Buka handel lain ke file untuk melakukan I/O.

Langkah ketiga membuat ini praktis hanya untuk oplock filter. Handel yang dibuka di langkah 3 dapat memiliki DesiredAccess yang berisi maksimum FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SINKRONKAN | READ_CONTROL dan masih belum merusak oplock filter. Namun, DesiredAccess apa pun yang lebih besar dari FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE akan merusak oplock tingkat 1 atau batch dan membuat bendera FILE_RESERVE_OPFILTER tidak berguna untuk jenis oplock tersebut.

NTFS adalah satu-satunya sistem file Microsoft yang menerapkan FILE_RESERVE_OPFILTER.

Driver minifilter harus menggunakan FltSetInformationFile, bukan ZwSetInformationFile, untuk mengganti nama file.

Catatan

Jika Anda mencoba membuka volume tetapi hanya menentukan kombinasi bendera berikut untuk parameter DesiredAccess , FltCreateFileEx2 akan membuka handel, terlepas dari sistem file, yang memiliki akses langsung ke perangkat penyimpanan untuk volume.

FILE_READ_ATTRIBUTES
READ_CONTROL
WRITE_DAC
WRITE_OWNER
MENSINKRONISASI

Anda tidak boleh menggunakan FltCreateFileEx2 untuk membuka handel dengan akses langsung ke perangkat penyimpanan untuk volume atau Anda akan membocorkan sumber daya sistem. Jika Anda ingin membuka handel dengan akses langsung ke perangkat penyimpanan, panggil fungsi IoCreateFileEx, IoCreateFileSpecifyDeviceObjectHint, atau ZwCreateFile sebagai gantinya.

Ketika penelepon FltCreateFileEx2 ingin mengaktifkan reparsing untuk target volume, FLT_CREATEFILE_TARGET_ECP_CONTEXT dapat disertakan sebagai ECP ke daftar ECP dalam parameter DriverContext . Jika ECP ini ada, FltCreateFileEx2 akan menyesuaikan perangkat target untuk operasi pembuatan dan mencoba menemukan instans volume yang difilter yang sesuai untuk informasi file yang diberikan. Penggunaan ECP ini tersedia dimulai dengan Windows 8.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows Vista.
Target Platform	Universal
Header	fltkernel.h (termasuk FltKernel.h)
Pustaka	Fltmgr.lib
IRQL	PASSIVE_LEVEL