Fungsi IoCreateFileEx (ntddk.h)

Artikel
03/08/2023

Rutinitas IoCreateFileEx menyebabkan file atau direktori baru dibuat, atau membuka file, perangkat, direktori, atau volume yang ada dan memberi pemanggil handel untuk objek file. Driver filter sistem file (driver filter warisan) memanggil rutinitas ini.

Sintaks

NTSTATUS IoCreateFileEx(
  [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                     Disposition,
  [in]           ULONG                     CreateOptions,
  [in, optional] PVOID                     EaBuffer,
  [in]           ULONG                     EaLength,
  [in]           CREATE_FILE_TYPE          CreateFileType,
  [in, optional] PVOID                     InternalParameters,
  [in]           ULONG                     Options,
  [in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Parameter

[out] FileHandle

Penunjuk ke variabel yang menerima handel file jika panggilan berhasil. Driver harus menutup handel dengan ZwClose segera setelah handel tidak lagi digunakan.

[in] DesiredAccess

Bitmask bendera (lihat ACCESS_MASK) yang menentukan jenis akses yang diperlukan pemanggil ke file atau direktori. Kumpulan bendera DesiredAccess yang ditentukan sistem ini menentukan hak akses khusus berikut untuk objek file.

Bendera DesiredAccess	Makna
DELETE	File dapat dihapus.
FILE_READ_DATA	Data dapat dibaca dari file .
FILE_READ_ATTRIBUTES	Bendera FileAttributes , yang dijelaskan di bawah ini, dapat dibaca.
FILE_READ_EA	Atribut yang diperluas (EA) yang terkait dengan file dapat dibaca.
READ_CONTROL	Daftar kontrol akses (ACL) dan informasi kepemilikan yang terkait dengan file dapat dibaca.
FILE_WRITE_DATA	Data dapat ditulis ke file.
FILE_WRITE_ATTRIBUTES	Bendera FileAttributes dapat ditulis.
FILE_WRITE_EA	EA yang terkait dengan file dapat ditulis.
FILE_APPEND_DATA	Data dapat ditambahkan ke file.
WRITE_DAC	Daftar kontrol akses diskresi (DACL) yang terkait dengan file dapat ditulis.
WRITE_OWNER	Informasi kepemilikan yang terkait dengan file dapat ditulis.
MENSINKRONISASI	Pemanggil dapat menyinkronkan penyelesaian operasi I/O dengan menunggu FileHandle yang dikembalikan diatur ke status Sinyal. Bendera ini harus diatur jika bendera CreateOptions FILE_SYNCHRONOUS_IO_ALERT atau FILE_SYNCHRONOUS_IO_NONALERT diatur.
FILE_EXECUTE	Data dapat dibaca ke dalam memori dari file menggunakan I/O halaman sistem.

Atau, untuk objek file apa pun yang tidak mewakili direktori, Anda dapat menentukan satu atau beberapa bendera ACCESS_MASK generik berikut. Bendera STANDARD_RIGHTS_XXX adalah nilai sistem yang telah ditentukan sebelumnya yang digunakan untuk menegakkan keamanan pada objek sistem. Anda juga dapat menggabungkan bendera generik ini dengan bendera tambahan dari tabel sebelumnya.

Akses yang diinginkan ke nilai file	Peta ke bendera DesiredAccess
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA, SINKRONKAN.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA, SINKRONKAN.
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, SINKRONKAN, FILE_READ_ATTRIBUTES, FILE_EXECUTE.

Untuk direktori (bendera FILE_DIRECTORY_FILE CreateOptions diatur), Anda dapat menentukan satu atau beberapa bendera ACCESS_MASK berikut, yang juga dapat Anda gabungkan dengan bendera yang kompatibel yang dijelaskan sebelumnya.

Akses yang diinginkan ke nilai direktori	Makna
FILE_LIST_DIRECTORY	File dalam direktori dapat dicantumkan.
FILE_TRAVERSE	Direktori dapat dilalui; yaitu, dapat menjadi bagian dari nama jalur file.

Bendera FILE_READ_DATA, FILE_WRITE_DATA, FILE_EXECUTE, dan FILE_APPEND_DATA DesiredAccess tidak kompatibel dengan membuat atau membuka file direktori.

[in] ObjectAttributes

Penunjuk ke struktur OBJECT_ATTRIBUTES yang sudah diinisialisasi oleh rutinitas InitializeObjectAttributes . Jika pemanggil berjalan dalam konteks proses sistem, parameter ini bisa null. Jika tidak, penelepon harus mengatur atribut OBJ_KERNEL_HANDLE dalam panggilan ke InitializeObjectAttributes. Anggota struktur ini untuk objek file mencakup yang berikut ini.

Anggota	Nilai
Panjang ULONG	Jumlah byte dari data ObjectAttributes yang disediakan. Nilai ini harus setidaknya `sizeof(OBJECT_ATTRIBUTES)`.
PUNICODE_STRING ObjectName	Penunjuk ke string Unicode buffer yang berisi nama file yang akan dibuat atau dibuka. Nilai ini harus merupakan spesifikasi file yang sepenuhnya memenuhi syarat, kecuali itu adalah nama file yang relatif terhadap direktori yang ditentukan oleh RootDirectory. Misalnya, "\Device\Floppy1\myfile.dat" atau "?? \B:\myfile.dat" bisa menjadi spesifikasi file yang sepenuhnya memenuhi syarat, selama driver disket dan sistem file yang terlalu besar sudah dimuat. (Catatan: "??" menggantikan "\DosDevices" sebagai nama namespace objek Win32. "\DosDevices" masih berfungsi, tetapi "??" diterjemahkan lebih cepat oleh manajer objek.)
HANDLE RootDirectory	Handel opsional ke direktori yang diperoleh oleh panggilan sebelumnya ke IoCreateFileEx. Jika nilai ini NULL, anggota ObjectName harus menjadi spesifikasi file yang sepenuhnya memenuhi syarat yang menyertakan jalur lengkap ke file target. Jika nilai ini bukan NULL, anggota ObjectName menentukan nama file yang relatif terhadap direktori ini.
PSECURITY_DESCRIPTOR SecurityDescriptor	Deskriptor keamanan opsional yang akan diterapkan ke file. ACL yang ditentukan oleh deskriptor keamanan seperti itu hanya diterapkan ke file saat dibuat. Jika nilainya ADALAH NULL saat file dibuat, ACL yang ditempatkan pada file bergantung pada sistem file; sebagian besar sistem file menyebarkan beberapa bagian dari ACL seperti itu dari file direktori induk yang dikombinasikan dengan ACL default pemanggil.
Atribut ULONG	Sekumpulan bendera yang mengontrol atribut objek file. Jika pemanggil berjalan dalam konteks proses sistem, parameter ini bisa nol. Jika tidak, pemanggil harus mengatur bendera OBJ_KERNEL_HANDLE . Pemanggil juga dapat secara opsional mengatur bendera OBJ_CASE_INSENSITIVE , yang menunjukkan bahwa kode pencarian nama harus mengabaikan kasus ObjectName alih-alih melakukan pencarian yang sama persis.

[out] IoStatusBlock

Penunjuk ke variabel jenis IO_STATUS_BLOCK yang menerima status penyelesaian akhir dan informasi tentang operasi yang diminta. Saat kembali dari IoCreateFileEx, anggota Informasi variabel berisi salah satu nilai berikut:

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

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

[in] FileAttributes

Atribut yang ditentukan secara eksplisit hanya diterapkan saat file dibuat, digantikan, atau, dalam beberapa kasus, ditimpa. Secara default, nilai ini FILE_ATTRIBUTE_NORMAL, yang dapat ditimpa oleh bendera lain atau dengan kombinasi (melalui operasi OR bitwise) dari bendera yang kompatibel. Bendera FileAttributes yang mungkin mencakup yang berikut ini.

Bendera FileAttributes	Makna
FILE_ATTRIBUTE_NORMAL	File yang memiliki atribut standar harus dibuat.
FILE_ATTRIBUTE_READONLY	File baca-saja harus dibuat.
FILE_ATTRIBUTE_HIDDEN	File tersembunyi harus dibuat.
FILE_ATTRIBUTE_SYSTEM	File sistem harus dibuat.
FILE_ATTRIBUTE_ARCHIVE	File harus ditandai sehingga akan diarsipkan.
FILE_ATTRIBUTE_TEMPORARY	File sementara harus dibuat.

[in] ShareAccess

Menentukan jenis akses berbagi ke file yang diinginkan pemanggil, sebagai nol, atau satu, atau kombinasi bendera berikut. Untuk meminta akses eksklusif, atur parameter ini ke nol. Jika bendera IO_IGNORE_SHARE_ACCESS_CHECK ditentukan dalam parameter Opsi , 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 ini, bahkan ketika Anda menggunakan bendera IO_IGNORE_SHARE_ACCESS_CHECK. Untuk membantu Anda menghindari kesalahan berbagi pelanggaran, tentukan semua bendera akses berbagi berikut.

Bendera ShareAccess	Makna
FILE_SHARE_READ	File dapat dibuka untuk akses baca oleh panggilan pembuatan file utas lainnya.
FILE_SHARE_WRITE	File dapat dibuka untuk akses tulis oleh panggilan pembuatan file utas lainnya.
FILE_SHARE_DELETE	File dapat dibuka untuk akses penghapusan oleh panggilan pembuatan file utas lainnya.

Driver perangkat dan driver perantara biasanya mengatur ShareAccess ke nol, yang memberi pemanggil akses eksklusif ke file terbuka.

[in] Disposition

Nilai yang menentukan bagaimana file harus ditangani ketika file sudah ada. Disposisi bisa menjadi salah satu dari berikut ini.

Nilai	Makna
FILE_SUPERSEDE	Jika file sudah ada, ganti dengan file yang diberikan. Jika tidak ada, buat file yang diberikan.
FILE_CREATE	Jika file sudah ada, gagalkan permintaan dan jangan membuat atau membuka file yang diberikan. Jika tidak ada, buat file yang diberikan.
FILE_OPEN	Jika file sudah ada, buka alih-alih membuat file baru. Jika tidak ada, gagalkan permintaan dan jangan buat file baru.
FILE_OPEN_IF	Jika file sudah ada, buka file tersebut. Jika tidak ada, buat file yang diberikan.
FILE_OVERWRITE	Jika file sudah ada, buka dan timpa. Jika tidak ada, gagalkan permintaan.
FILE_OVERWRITE_IF	Jika file sudah ada, buka dan timpa. Jika tidak ada, buat file yang diberikan.

[in] CreateOptions

Menentukan opsi yang akan diterapkan saat membuat atau membuka file, sebagai kombinasi bendera berikut yang kompatibel.

Bendera CreateOptions	Makna
FILE_DIRECTORY_FILE (0x00000001)	File yang sedang dibuat atau dibuka adalah file direktori. Dengan bendera ini, parameter Disposisi harus diatur ke salah satu FILE_CREATE, FILE_OPEN, atau FILE_OPEN_IF. Bendera CreateOptions yang kompatibel dengan bendera ini adalah sebagai berikut: FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT, dan FILE_OPEN_BY_FILE_ID.
FILE_WRITE_THROUGH (0x00000002)	Layanan sistem, sistem file, dan driver yang menulis data ke file harus benar-benar mentransfer data ke dalam file sebelum operasi tulis yang diminta dianggap selesai.
FILE_SEQUENTIAL_ONLY (0x00000004)	Semua akses ke file akan berurutan.
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008)	File tidak dapat di-cache atau di-buffer dalam buffer internal driver. Bendera ini tidak kompatibel dengan bendera FILE_APPEND_DATA DesiredAccess.
FILE_SYNCHRONOUS_IO_ALERT (0x00000010)	Semua operasi pada file dilakukan secara sinkron. Setiap tunggu atas nama pemanggil tunduk pada penghentian dini dari pemberitahuan. Bendera ini juga menyebabkan sistem I/O mempertahankan konteks posisi file. Jika bendera ini diatur, bendera DesiredAccess SYNCHRONIZE juga harus diatur sehingga Manajer I/O menggunakan objek file sebagai objek sinkronisasi.
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020)	Semua operasi pada file dilakukan secara sinkron. Menunggu dalam sistem untuk menyinkronkan antrean I/O dan penyelesaian tidak tunduk pada pemberitahuan. Bendera ini juga menyebabkan sistem I/O mempertahankan konteks posisi file. Jika bendera ini diatur, bendera DesiredAccess SYNCHRONIZE juga harus diatur sehingga Manajer I/O menggunakan objek file sebagai objek sinkronisasi.
FILE_NON_DIRECTORY_FILE (0x00000040)	File yang sedang dibuka tidak boleh berupa file direktori atau panggilan ini gagal. Objek file yang sedang dibuka dapat mewakili file data; perangkat logis, virtual, atau fisik; atau volume.
FILE_CREATE_TREE_CONNECTION (0x00000080)	Buat koneksi pohon untuk file ini untuk membukanya melalui jaringan.
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	Selesaikan operasi ini segera dengan kode keberhasilan alternatif jika file target di-oplock, daripada memblokir utas pemanggil. Jika file di-oplock, penelepon lain sudah memiliki akses ke file melalui jaringan.
FILE_NO_EA_KNOWLEDGE (0x00000200)	Jika atribut yang diperluas pada file yang ada dibuka menunjukkan bahwa pemanggil harus memahami atribut yang diperluas untuk menginterpretasikan file dengan benar, gagalkan permintaan ini karena pemanggil tidak memahami cara menangani atribut yang diperluas.
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	Dicadangkan untuk penggunaan sistem; jangan gunakan.
FILE_RANDOM_ACCESS (0x00000800)	Akses ke file bisa acak, jadi tidak ada operasi read-ahead berurutan yang harus dilakukan pada file dengan sistem file atau sistem operasi.
FILE_DELETE_ON_CLOSE (0x00001000)	Hapus file ketika handel terakhir diteruskan ke FltClose.
FILE_OPEN_BY_FILE_ID (0x00002000)	File sedang dibuka oleh ID. Nama file berisi nama perangkat dan ID 64-bit yang akan digunakan untuk membuka file.
FILE_OPEN_FOR_BACKUP_INTENT (0x000004000)	File sedang dibuka untuk tujuan pencadangan; oleh karena itu, sistem harus memeriksa hak akses tertentu dan memberi pemanggil akses yang sesuai ke file sebelum memeriksa input DesiredAccess terhadap deskriptor keamanan file.
FILE_NO_COMPRESSION (0x00008000)	Menekan warisan FILE_ATTRIBUTE_COMPRESSED dari direktori induk. Ini memungkinkan pembuatan file yang tidak dikompresi dalam direktori yang ditandai terkompresi.
FILE_OPEN_REQUIRING_OPLOCK (0x00010000)	File sedang dibuka dan kunci oportunistik (oplock) pada file diminta sebagai operasi atom tunggal. Sistem file memeriksa oplock sebelum melakukan operasi pembuatan, dan operasi pembuatan akan gagal dengan kode pengembalian STATUS_CANNOT_BREAK_OPLOCK jika operasi pembuatan akan merusak oplock yang ada. Bendera ini tersedia di Windows 7, Windows Server 2008 R2 dan sistem operasi Windows yang lebih baru.
FILE_DISALLOW_EXCLUSIVE (0x00020000)	Saat membuka file yang ada, jika FILE_SHARE_READ tidak ditentukan dan pemeriksaan akses sistem file tidak akan memberi pemanggil akses tulis ke file, gagal membuka ini dengan STATUS_ACCESS_DENIED. Ini adalah perilaku default sebelum Windows 7.
FILE_SESSION_AWARE (0x00040000)	File atau perangkat sedang dibuka dengan kesadaran sesi. Jika bendera ini tidak ditentukan, maka perangkat per sesi (seperti perangkat yang menggunakan Pengalihan USB RemoteFX) tidak dapat dibuka oleh proses yang berjalan di sesi 0. Bendera ini tidak berpengaruh bagi penelepon yang tidak berada di sesi 0. Bendera ini hanya didukung pada Windows edisi server. Bendera ini tidak didukung sebelum Windows Server 2012.
FILE_RESERVE_OPFILTER (0x00100000)	Bendera ini memungkinkan aplikasi untuk meminta kunci oportunistik filter (oplock) untuk mencegah aplikasi lain mendapatkan pelanggaran berbagi. Jika sudah ada handel terbuka, permintaan buat akan gagal dengan STATUS_OPLOCK_NOT_GRANTED. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
FILE_OPEN_REPARSE_POINT (0x00200000)	Buka file dengan titik pemisahan ulang dan lewati pemrosesan titik pemilah ulang normal untuk file. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
FILE_OPEN_NO_RECALL (0x00400000)	Menginstruksikan filter apa pun yang melakukan penyimpanan offline atau virtualisasi untuk tidak memanggil kembali konten file sebagai akibat dari pembukaan ini.
FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000)	Bendera ini menginstruksikan sistem file untuk menangkap pengguna yang terkait dengan utas panggilan. Setiap panggilan berikutnya ke FltQueryVolumeInformation atau ZwQueryVolumeInformationFile menggunakan handel yang dikembalikan akan mengasumsikan pengguna yang ditangkap, daripada pengguna panggilan pada saat itu, untuk tujuan menghitung ruang kosong yang tersedia untuk pemanggil. Berlaku untuk nilai FsInformationClass berikut: FileFsSizeInformation, FileFsFullSizeInformation, dan FileFsFullSizeInformationEx.

[in, optional] EaBuffer

Penunjuk ke variabel jenis yang disediakan penelepon FILE_FULL_EA_INFORMATION yang berisi informasi atribut yang diperluas (EA) untuk diterapkan ke file. Untuk driver perangkat dan perantara, parameter ini harus NULL.

[in] EaLength

Panjang, dalam byte, dari EaBuffer. Untuk driver perangkat dan driver perantara, parameter ini harus nol.

[in] CreateFileType

Driver harus mengatur parameter ini ke CreateFileTypeNone.

[in, optional] InternalParameters

Driver harus mengatur parameter ini ke NULL.

[in] Options

Menentukan opsi yang akan digunakan selama pembuatan permintaan pembuatan. Nol atau lebih dari nilai bendera bit berikut dapat digunakan.

Bendera opsi	Makna
IO_FORCE_ACCESS_CHECK	Manajer I/O harus memeriksa permintaan buat terhadap deskriptor keamanan file. Untuk informasi selengkapnya, lihat Keterangan.
IO_IGNORE_SHARE_ACCESS_CHECK	Manajer I/O tidak boleh melakukan pemeriksaan akses berbagi pada objek file setelah dibuat. Namun, sistem file mungkin masih melakukan pemeriksaan ini.
IO_STOP_ON_SYMLINK	Jika persimpangan, tautan simbolis, atau titik pemisahan ulang global ditemui saat membuka atau membuat file, manajer I/O akan mengembalikan STATUS_STOPPED_ON_SYMLINK. Selain itu, struktur REPARSE_DATA_BUFFER akan dikembalikan dalam IoStatusBlock-Information>. Pemanggil bertanggung jawab untuk membebaskan struktur REPARSE_DATA_BUFFER .
IO_OPEN_TARGET_DIRECTORY	Buka direktori induk file.

[in, optional] DriverContext

Penunjuk opsional ke struktur IO_DRIVER_CREATE_CONTEXT yang sebelumnya diinisialisasi oleh rutinitas IoInitializeDriverCreateContext . Struktur IO_DRIVER_CREATE_CONTEXT dapat digunakan untuk meneruskan parameter tambahan ke rutinitas IoCreateFileEx dan FltCreateFileEx2 . Lihat bagian Keterangan berikut untuk informasi selengkapnya.

Mengembalikan nilai

IoCreateFileEx mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai seperti salah satu hal berikut ini.

Menampilkan kode	Deskripsi
STATUS_INVALID_DEVICE_OBJECT_PARAMETER	IoCreateFileEx mengembalikan nilai status ini jika parameter DriverContext bukan NULL dan jika objek perangkat yang ditentukan tidak dilampirkan ke tumpukan driver sistem file untuk volume yang ditentukan dalam nama file atau direktori. Objek perangkat ini ditentukan oleh anggota DeviceObjectHint dari struktur IO_DRIVER_CREATE_CONTEXT. Untuk informasi selengkapnya, lihat IO_DRIVER_CREATE_CONTEXT.
STATUS_MOUNT_POINT_NOT_RESOLVED	IoCreateFileEx mengembalikan nilai status ini jika parameter DriverContext bukan NULL dan jika nama file atau direktori berisi titik pemasangan yang diselesaikan ke volume selain yang dilampirkan objek perangkat yang ditentukan. Objek perangkat ini ditentukan oleh anggota DeviceObjectHint dari struktur IO_DRIVER_CREATE_CONTEXT. Untuk informasi selengkapnya, lihat IO_DRIVER_CREATE_CONTEXT.
STATUS_OBJECT_PATH_SYNTAX_BAD	IoCreateFileEx mengembalikan nilai status ini jika parameter ObjectAttributes tidak berisi anggota RootDirectory , tetapi anggota ObjectName dalam struktur OBJECT_ATTRIBUTES adalah string kosong atau tidak berisi karakter OBJECT_NAME_PATH_SEPARATOR. Ini menunjukkan sintaks yang salah untuk jalur objek.
STATUS_STOPPED_ON_SYMLINK	IoCreateFileEx mengembalikan nilai status ini jika bendera parameter OpsiIO_STOP_ON_SYMLINK diatur dan tautan simbolis ditemui saat membuka atau membuat file.

Jika rutinitas IoCreateFileEx mengembalikan status kesalahan, pemanggil dapat menemukan informasi tambahan tentang penyebab kegagalan dengan memeriksa parameter IoStatusBlock .

IoCreateFileEx mungkin mengembalikan STATUS_FILE_LOCK_CONFLICT sebagai nilai yang dikembalikan 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 IoCreateFileEx mencoba menangani situasi ini.

Keterangan

Rutinitas IoCreateFileEx mirip dengan rutinitas IoCreateFile dan rutinitas IoCreateFileSpecifyDeviceObjectHint tetapi menawarkan fungsionalitas tambahan termasuk akses ke parameter buat ekstra (ECP), petunjuk objek perangkat, dan informasi transaksi melalui parameter DriverContext rutin IoCreateFileEx. Untuk informasi selengkapnya tentang parameter berbasis struktur ini, lihat IO_DRIVER_CREATE_CONTEXT.

Driver filter sistem file memanggil IoCreateFileEx untuk mengirim permintaan buat hanya ke objek perangkat tertentu, filter yang terpasang di bawahnya, dan sistem file. Filter yang terpasang di atas objek perangkat yang ditentukan di tumpukan driver tidak menerima permintaan buat. Namun, jika anggota DeviceObjectHint dari struktur IO_DRIVER_CREATE_CONTEXT (melewati parameter DriverContext ) adalah NULL, permintaan masuk ke bagian atas tumpukan dan diterima oleh semua filter dan sistem file.

Jika permintaan I/O tidak masuk ke bagian atas tumpukan driver, yaitu jika parameter DriverContext bukan NULL dan objek perangkat yang valid ditentukan oleh anggota DeviceObjectHint dari struktur IO_DRIVER_CREATE_CONTEXT, pembatasan berikut berlaku:

Jika jalur nama file yang diteruskan ke rutinitas IoCreateFileEx berisi titik pemasangan, titik pemasangan harus diselesaikan ke volume yang sama tempat file atau direktori berada.

Handel yang diperoleh oleh IoCreateFileEx dapat digunakan oleh panggilan berikutnya untuk memanipulasi data dalam file atau status atau atribut objek file. Setiap handel yang diperoleh dari IoCreateFileEx akhirnya harus dirilis dengan memanggil ZwClose.

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

Sebagai nama jalur yang sepenuhnya memenuhi syarat, disediakan dalam anggota ObjectName dari parameter ObjectAttributes input.
Sebagai nama jalur relatif terhadap handel di anggota RootDirectory dari parameter ObjectAttributes input. (Handel ini dapat mewakili file direktori.)

Rutinitas driver yang berjalan dalam konteks proses selain dari proses sistem harus mengatur atribut OBJ_KERNEL_HANDLE untuk parameter ObjectAttributesIoCreateFileEx. Ini membatasi penggunaan handel yang dikembalikan oleh IoCreateFileEx untuk memproses yang berjalan dalam mode kernel. Jika tidak, handel dapat diakses oleh proses dalam konteks driver yang berjalan. Driver dapat memanggil InitializeObjectAttributes untuk mengatur atribut OBJ_KERNEL_HANDLE.

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 tidak, pemanggil yang merupakan perangkat atau driver perantara harus menyinkronkan penyelesaian I/O dengan menggunakan objek peristiwa.
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 akan secara otomatis diperpanjang seperlunya untuk operasi tulis semacam ini.
Mengatur bendera FILE_WRITE_DATA untuk file juga memungkinkan penulisan di luar akhir file terjadi. File ini secara otomatis diperluas untuk penulisan semacam ini juga.
Jika hanya bendera FILE_EXECUTE dan SYNCHRONIZE yang diatur, pemanggil tidak dapat langsung membaca atau menulis data apa pun dalam file menggunakan FileHandle yang dikembalikan: yaitu, semua operasi pada file terjadi melalui pager sistem sebagai respons terhadap instruksi dan akses data. Perangkat dan driver perantara tidak boleh mengatur bendera FILE_EXECUTE di DesiredAccess.

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

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

Jika IO_IGNORE_SHARE_ACCESS_CHECK ditentukan dalam parameter Opsi , 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.

Nilai Disposisi FILE_SUPERSEDE mengharuskan pemanggil memiliki akses DELETE ke objek file yang ada. Jika demikian, panggilan yang berhasil ke IoCreateFileEx 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, utas membuka file dengan menentukan parameter ShareAccess dengan set bendera FILE_SHARE_DELETE. Perhatikan bahwa jenis disposisi ini konsisten dengan gaya POSIX menimpa file.

Nilai Disposisi FILE_OVERWRITE_IF dan FILE_SUPERSEDE serupa. Jika IoCreateFileEx dipanggil dengan file yang ada dan salah satu nilai Disposisi ini, file akan diganti.

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

Pemanggil harus memiliki akses tulis ke file, alih-alih 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 IoCreateFileEx 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 dengan 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 Disposition yang tidak konsisten, panggilan ke IoCreateFileEx akan 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 ByteOffset opsional yang diteruskan ke ZwReadFile atau ZwWriteFile harus merupakan integral (kelipatan bilangan bulat) dari ukuran sektor.
Panjang yang diteruskan ke ZwReadFile atau ZwWriteFile, harus merupakan integral dari ukuran sektor. Perhatikan bahwa menentukan operasi baca ke buffer yang panjangnya persis dengan ukuran sektor dapat mengakibatkan lebih sedikit jumlah byte signifikan yang ditransfer ke buffer tersebut jika akhir file tercapai selama transfer.
Buffer harus diselaraskan sesuai dengan persyaratan penyelarasan perangkat yang mendasar. Informasi ini dapat diperoleh dengan memanggil IoCreateFileEx untuk mendapatkan handel untuk objek file yang mewakili perangkat fisik, dan, kemudian, memanggil ZwQueryInformationFile dengan handel tersebut. Untuk daftar nilai sistem FILE_XXX_ALIGNMENT, lihat DEVICE_OBJECT.
Panggilan ke ZwSetInformationFile dengan parameter FileInformationClass yang diatur ke FilePositionInformation harus menentukan offset yang merupakan integral dari ukuran sektor.

Bendera CreateOptions, FILE_SYNCHRONOUS_IO_ALERT, dan FILE_SYNCHRONOUS_IO_NONALERT yang saling eksklusif, menentukan bahwa semua operasi I/O pada file harus sinkron selama terjadi melalui objek file yang dimaksud oleh FileHandle yang dikembalikan. Semua I/O pada file tersebut diserialisasikan di semua utas dengan menggunakan handel yang dikembalikan. Dengan salah satu nilai CreateOptions ini, bendera DesiredAccess SYNCHRONIZE harus diatur sehingga Manajer I/O akan menggunakan objek file sebagai objek sinkronisasi. Dengan salah satu nilai CreateOptions ini ditetapkan, Manajer I/O mempertahankan "konteks posisi file" untuk objek file, offset posisi file internal saat ini. Offset ini dapat digunakan dalam panggilan ke ZwReadFile dan ZwWriteFile. Posisinya juga dapat dikueri dengan memanggil ZwQueryInformationFile, atau diatur dengan memanggil ZwSetInformationFile.

Jika bendera CreateOptions FILE_OPEN_REPARSE_POINT tidak ditentukan dan IoCreateFileEx mencoba membuka file dengan titik pemilah 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 IoCreateFileEx mencoba untuk langsung membuka file titik reparse. Dalam kedua kasus, jika operasi terbuka berhasil, IoCreateFileEx mengembalikan STATUS_SUCCESS; jika tidak, rutinitas mengembalikan kode kesalahan NTSTATUS. IoCreateFileEx 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 IoCreateFileEx 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.

Bendera FILE_OPEN_REQUIRING_OPLOCK tersedia di Windows 7, Windows Server 2008 R2dan sistem operasi Windows yang lebih baru. Sistem file Microsoft yang mengimplementasikan bendera ini 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 mengikuti langkah-langkah berikut:

Terbitkan permintaan buat dengan CreateOptions FILE_RESERVE_OPFILTER, DesiredAccess dari FILE_READ_ATTRIBUTES yang tepat, dan ShareAccess dari FILE_SHARE_READ yang tepat | 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.

Untuk membuat permintaan yang berasal dari mode pengguna, jika driver mengatur IO_FORCE_ACCESS_CHECK dalam parameter OpsiIoCreateFileEx maka itu juga harus mengatur OBJ_FORCE_ACCESS_CHECK dalam parameter ObjectAttributes . Untuk informasi tentang bendera ini, lihat anggota AtributOBJECT_ATTRIBUTES.

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

IoCreateFileEx dapat digunakan untuk mendapatkan handel ke volume.