Fungsi FltCreateFile (fltkernel.h)

Artikel
08/07/2023

Driver minifilter memanggil FltCreateFile untuk membuat file baru atau membuka file yang ada.

Sintaks

NTSTATUS FLTAPI FltCreateFile(
  [in]           PFLT_FILTER        Filter,
  [in, optional] PFLT_INSTANCE      Instance,
  [out]          PHANDLE            FileHandle,
  [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
);

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 bukan NULL, permintaan hanya dikirim ke instans driver minifilter yang dilampirkan di bawah instans yang ditentukan.

[out] FileHandle

Penunjuk ke variabel yang dialokasikan pemanggil yang menerima handel file jika panggilan ke FltCreateFile berhasil.

[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

Pointer 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 ShareAccessIoCreateFileEx untuk detail selengkapnya dan untuk daftar bendera.

[in] CreateDisposition

Menentukan nilai yang menentukan tindakan yang akan diambil, tergantung 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 CreateOptionsIoCreateFileEx.

[in, optional] EaBuffer

Penunjuk ke buffer terstruktur 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.

Nilai kembali

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

Catatan

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

Keterangan

Pada versi Windows yang lebih lama dari Microsoft Windows Update Rollup untuk Windows 2000 SP4 dan Windows Server 2003 SP1, driver minifilter harus memanggil FltCreateFile alih-alih IoCreateFile, IoCreateFileSpecifyDeviceObjectHint, atau ZwCreateFile untuk mendapatkan handel file untuk digunakan dengan rutinitas I/O ZwXxx seperti ZwReadFile dan ZwQueryInformationFile.

Pada Microsoft Windows Update Rollup untuk Windows 2000 SP4, Windows Server 2003 SP1 dan yang lebih baru, driver minifilter dapat menggunakan FltCreateFileEx untuk mendapatkan penunjuk objek file untuk digunakan dengan rutinitas File FltXxx seperti FltReadFile dan FltWriteFile. Pada versi Windows yang lebih lama, handel yang diperoleh dari FltCreateFile dapat dikonversi menjadi penunjuk objek file dengan memanggil ObReferenceObjectByHandle sebagai berikut:

status = ObReferenceObjectByHandle(
           handle,                 //Handle
           0,                      //DesiredAccess
           NULL,                   //ObjectType
           KernelMode,             //AccessMode
           &handleFileObject,      //Object
           NULL);                  //HandleInformation</pre>

FltCreateFile 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 FltCreateFile:

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

Setiap handel yang diperoleh dari FltCreateFile pada akhirnya harus dirilis dengan memanggil FltClose.

Rutinitas driver yang tidak berjalan dalam konteks proses sistem harus mengatur atribut OBJ_KERNEL_HANDLE untuk parameter ObjectAttributesFltCreateFile. Mengatur atribut ini membatasi penggunaan handel yang dikembalikan oleh FltCreateFile untuk memproses 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.

Jangan sebut rutinitas ini dengan APC dinonaktifkan ( FsRtlEnterFileSystem atau KeEnterCriticalRegion yang luar biasa, karena ini dapat menyebabkan kebuntuan utas.

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 penulisan ke file diabaikan. Namun, file secara otomatis diperluas seperlunya untuk jenis operasi tulis ini.
Mengatur bendera FILE_WRITE_DATA untuk file juga memungkinkan penulisan di luar akhir file terjadi. File secara otomatis diperluas untuk jenis penulisan ini juga.
Jika hanya bendera FILE_EXECUTE dan SYNCHRONIZE yang diatur, pemanggil tidak dapat menggunakan FileHandle yang dikembalikan 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 FltCreateFile 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 bukaan sebelumnya yang belum dirilis dengan FltClose. Artinya, DesiredAccess yang ditentukan ke FltCreateFile 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 FltCreateFile dengan FILE_SUPERSEDE pada file yang ada secara efektif menghapus file tersebut lalu membuatnya kembali. Ini menyiratkan bahwa jika file telah dibuka oleh utas lain, file akan dibuka dengan menentukan parameter ShareAccess dengan 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 FltCreateFile 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 input ShareAccess.
Atribut file yang ditentukan secara logis ORed dengan yang sudah ada di file. Ini menyiratkan bahwa jika file telah dibuka oleh utas lain, penelepon berikutnya dari FltCreateFile 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 FltCreateFile gagal.

Bendera createOptions FILE_NO_INTERMEDIATE_BUFFERING mencegah sistem file melakukan buffering perantara atas nama pemanggil. Menentukan nilai ini menempatkan batasan tertentu pada parameter pemanggil ke Zw.. Rutinitas file, termasuk yang berikut ini:

Setiap nilai Byte Offset yang diteruskan ke ZwReadFile atau ZwWriteFile harus berupa kelipatan ukuran sektor.
Panjang yang diteruskan ke ZwReadFile atau ZwWriteFile harus berupa 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 FltCreateFile untuk mendapatkan handel untuk objek file yang mewakili perangkat fisik dan kemudian memanggil ZwQueryInformationFile dengan handel tersebut, menentukan FileAlignmentInformation sebagai FileInformationClass. Untuk informasi selengkapnya tentang sistem FILE_XXX_ALIGNMENT nilai, yang ditentukan dalam ntifs.h, lihat DEVICE_OBJECT dan Menginisialisasi Objek Perangkat.
Panggilan ke ZwSetInformationFile dengan parameter FileInformationClass yang diatur ke FilePositionInformation harus menentukan offset yang merupakan kelipatan ukuran sektor.

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 oleh FileHandle yang dikembalikan. Semua I/O pada file tersebut diserialisasikan di semua utas dengan menggunakan handel yang dikembalikan. Dengan salah satu set CreateOptions ini, 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 FltCreateFile mencoba membuka file dengan titik pemisahan ulang, pemrosesan titik pemisahan ulang normal terjadi untuk file. Jika, di sisi lain, bendera FILE_OPEN_REPARSE_POINT ditentukan, pemrosesan reparse normal tidak terjadi dan FltCreateFile mencoba untuk langsung membuka file titik reparse. Dalam kedua kasus, jika operasi terbuka berhasil, FltCreateFile mengembalikan STATUS_SUCCESS; jika tidak, rutinitas mengembalikan kode kesalahan NTSTATUS. FltCreateFile 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 FltCreateFile lalu meminta oplock apa pun. Ini memastikan bahwa pemilik oplock akan diberi tahu tentang permintaan terbuka apa pun 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 tingkat 1, batch, atau filter oplock 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 persis, dan ShareAccess dari FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- Jika sudah ada handel terbuka, permintaan buat gagal dengan STATUS_OPLOCK_NOT_GRANTED, dan oplock yang diminta berikutnya 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 | MENYINKRONKAN | READ_CONTROL dan masih tidak 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 , FltCreateFile 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 FltCreateFile 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.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Update Rollup 1 untuk SP4, Windows XP SP2, Windows Server 2003 SP1
Target Platform	Universal
Header	fltkernel.h (termasuk FltKernel.h)
Pustaka	Fltmgr.lib
IRQL	PASSIVE_LEVEL