Bagikan melalui

Fungsi NtCreateFile (ntifs.h)

  • Artikel

Rutinitas NtCreateFile membuat file baru atau membuka file yang sudah ada.

Sintaks

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateFile(
  [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
);

Parameter

[out] FileHandle

Penunjuk ke variabel HANDLE yang menerima handel ke file.

[in] DesiredAccess

Menentukan nilai ACCESS_MASK yang menentukan akses yang diminta ke objek.

Selain hak akses standar yang ditentukan untuk semua jenis objek, pemanggil dapat menentukan salah satu hak akses spesifik berikut; yaitu, hak yang khusus untuk file.

bendera ACCESS_MASK Memungkinkan penelepon untuk melakukan ini
FILE_READ_DATA Membaca data dari file.
FILE_READ_ATTRIBUTES Baca atribut file. Untuk informasi selengkapnya, lihat deskripsi parameter FileAttributes .
FILE_READ_EA Baca atribut yang diperluas (EA) file. Bendera ini tidak relevan untuk driver perangkat dan perantara.
FILE_WRITE_DATA Tulis data ke file.
FILE_WRITE_ATTRIBUTES Tulis atribut file. Untuk informasi selengkapnya, lihat deskripsi parameter FileAttributes .
FILE_WRITE_EA Ubah atribut yang diperluas (EA) file. Bendera ini tidak relevan untuk driver perangkat dan perantara.
FILE_APPEND_DATA Tambahkan data ke file.
FILE_EXECUTE Gunakan I/O halaman sistem untuk membaca data dari file ke dalam memori. Bendera ini tidak relevan untuk driver perangkat dan perantara.

Catatan

Jangan tentukan FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA, atau FILE_EXECUTE saat Anda membuat atau membuka direktori.

Pemanggil juga dapat menentukan hak akses generik berikut (hak yang berlaku untuk semua jenis objek, di mana arti setiap hak akses generik khusus untuk jenis objek). Hak akses generik untuk objek file sesuai dengan hak akses tertentu seperti yang diperlihatkan dalam tabel berikut. (Perhatikan bahwa "sesuai" berarti "peta ke" dan tidak berarti bahwa nilai hak generik "sama dengan" nilai bitwise ATAU pemetaan hak spesifiknya). Manajer I/O mendefinisikan pemetaan yang sebenarnya.

Akses generik ke kanan Memetakan hak akses khusus ini
GENERIC_READ STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA, dan SINKRONKAN
GENERIC_WRITE STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA, dan SINKRONKAN
GENERIC_EXECUTE STANDARD_RIGHTS_EXECUTE, FILE_EXECUTE, FILE_READ_ATTRIBUTES, dan SINKRONKAN. Nilai ini tidak relevan untuk perangkat dan driver perantara.
GENERIC_ALL FILE_ALL_ACCESS

Catatan

Hak akses generik hanya dapat ditentukan untuk file; mereka tidak dapat ditentukan untuk direktori.

Beberapa bendera CreateOptions mengharuskan bendera akses tertentu diatur dalam DesiredAccess saat NtCreateFile dipanggil. Lihat parameter CreateOptions untuk detail ini.

Misalnya, jika Anda menentukan GENERIC_READ untuk objek file, rutin memetakan nilai ini ke bitmask FILE_GENERIC_READ hak akses tertentu. Dalam tabel sebelumnya, hak akses khusus yang tercantum untuk GENERIC_READ sesuai dengan (tetapi tidak sama dengan) bendera akses yang terkandung dalam bitmask FILE_GENERIC_READ.

Jika file sebenarnya adalah direktori, pemanggil juga dapat menentukan hak akses generik berikut.

Bendera DesiredAccess Memungkinkan penelepon untuk melakukan ini
FILE_LIST_DIRECTORY Cantumkan file dalam direktori.
FILE_TRAVERSE Melintasi direktori, dengan kata lain, menyertakan direktori di jalur file.

Untuk informasi selengkapnya tentang hak akses, lihat ACCESS_MASK dan Hak Akses.

[in] ObjectAttributes

Penunjuk ke struktur OBJECT_ATTRIBUTES yang menentukan nama objek dan atribut lainnya. Gunakan InitializeObjectAttributes untuk menginisialisasi struktur ini. Jika penelepon tidak berjalan dalam konteks utas sistem, pemanggil harus mengatur atribut OBJ_KERNEL_HANDLE saat memanggil InitializeObjectAttributes.

[out] IoStatusBlock

Penunjuk ke struktur IO_STATUS_BLOCK yang menerima status penyelesaian akhir dan informasi lain tentang operasi yang diminta. Secara khusus, anggota Informasi menerima salah satu nilai berikut:

  • FILE_CREATED
  • FILE_OPENED
  • FILE_OVERWRITTEN
  • FILE_SUPERSEDED
  • FILE_EXISTS
  • FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

Penunjuk ke LARGE_INTEGER yang berisi ukuran alokasi awal, dalam byte, untuk file yang dibuat atau ditimpa. Jika AllocationSizeadalah NULL, tidak ada ukuran alokasi yang ditentukan. Jika tidak ada file yang dibuat atau ditimpa, AllocationSize diabaikan.

[in] FileAttributes

Menentukan satu atau beberapa bendera FILE_ATTRIBUTE_XXX , yang mewakili atribut file yang akan diatur jika Anda membuat atau menimpa file. Pemanggil biasanya menentukan FILE_ATTRIBUTE_NORMAL, yang mengatur atribut default. Untuk daftar bendera FILE_ATTRIBUTE_XXX yang valid, lihat rutinitas CreateFile dalam dokumentasi Microsoft Windows SDK. Jika tidak ada file yang dibuat atau ditimpa, FileAttributes diabaikan.

[in] ShareAccess

Jenis akses berbagi, yang ditentukan sebagai nol atau kombinasi bendera berikut.

Bendera ShareAccess Memungkinkan utas lain untuk melakukan ini
FILE_SHARE_READ Membaca file
FILE_SHARE_WRITE Menulis file
FILE_SHARE_DELETE Menghapus file

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

[in] CreateDisposition

Menentukan tindakan yang akan dilakukan jika file tidak atau tidak ada. CreateDisposition bisa menjadi salah satu nilai dalam tabel berikut.

Nilai CreateDisposition Tindakan jika ada file Tindakan jika file tidak ada
FILE_SUPERSEDE Ganti file. Buat file.
FILE_CREATE Mengembalikan kesalahan. Buat file.
FILE_OPEN Buka file. Mengembalikan kesalahan.
FILE_OPEN_IF Buka file. Buat file.
FILE_OVERWRITE Buka file, dan timpa. Mengembalikan kesalahan.
FILE_OVERWRITE_IF Buka file, dan timpa. Buat file.

[in] CreateOptions

Menentukan opsi yang akan diterapkan ketika driver membuat atau membuka file. Gunakan satu atau beberapa bendera dalam tabel berikut.

Bendera CreateOptions Makna
FILE_DIRECTORY_FILE (0x00000001) File adalah direktori. Bendera CreateOptions yang kompatibel adalah FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT, dan FILE_OPEN_BY_FILE_ID. Parameter CreateDisposition harus diatur ke FILE_CREATE, FILE_OPEN, atau FILE_OPEN_IF.
FILE_WRITE_THROUGH (0x00000002) Layanan sistem, driver sistem file, dan driver yang menulis data ke file harus benar-benar mentransfer data ke 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 parameter DesiredAccess .
FILE_SYNCHRONOUS_IO_ALERT (0x00000010) Semua operasi pada file dilakukan secara sinkron. Setiap penantian atas nama penelepon tunduk pada penghentian dini dari pemberitahuan. Bendera ini juga menyebabkan sistem I/O mempertahankan penunjuk posisi file. Jika bendera ini diatur, bendera SYNCHRONIZE harus diatur dalam parameter DesiredAccess .
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020) Semua operasi pada file dilakukan secara sinkron. Menunggu di sistem yang 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 SYNCHRONIZE harus diatur dalam parameter DesiredAccess .
FILE_NON_DIRECTORY_FILE (0x00000040) File bukan direktori . Objek file yang akan dibuka dapat mewakili file data; perangkat logis, virtual, atau fisik; atau volume. Mulai Windows 11, versi 24H2, NTFS sekarang menghormati bendera ini saat membuka atribut $INDEX_ALLOCATION.
FILE_CREATE_TREE_CONNECTION (0x00000080) Create koneksi pohon untuk file ini untuk membukanya melalui jaringan. Bendera ini tidak digunakan oleh perangkat dan driver perantara.
FILE_COMPLETE_IF_OPLOCKED (0x00000100) Selesaikan operasi ini segera dengan kode keberhasilan alternatif STATUS_OPLOCK_BREAK_IN_PROGRESS jika file target di-oplock, daripada memblokir utas pemanggil. Jika file di-oplock, pemanggil lain sudah memiliki akses ke file. Bendera ini tidak digunakan oleh perangkat dan driver perantara.
FILE_NO_EA_KNOWLEDGE (0x00000200) Jika atribut yang diperluas (EA) untuk file yang ada dibuka menunjukkan bahwa pemanggil harus memahami EA untuk menginterpretasikan file dengan benar, NtCreateFile harus mengembalikan kesalahan. Bendera ini tidak relevan untuk driver perangkat dan perantara.
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 oleh driver sistem file atau oleh sistem.
FILE_DELETE_ON_CLOSE (0x00001000) Sistem menghapus file ketika handel terakhir ke file diteruskan ke NtClose. Jika bendera ini diatur, bendera DELETE harus diatur dalam parameter DesiredAccess .
FILE_OPEN_BY_FILE_ID (0x00002000) Nama file yang ditentukan oleh parameter ObjectAttributes menyertakan nomor referensi file biner 8-byte atau 16-byte atau ID objek untuk file, tergantung pada sistem file. Secara opsional, nama perangkat yang diikuti oleh karakter garis miring terbelakang dapat melanjutkan nilai biner ini. Lihat Keterangan untuk detail tambahan dan contohnya.
FILE_OPEN_FOR_BACKUP_INTENT (0x00004000) 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 parameter DesiredAccess terhadap pendeskripsi keamanan file. Bendera ini tidak digunakan oleh perangkat dan driver perantara.
FILE_NO_COMPRESSION (0x00008000) Menekan pewarisan 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 sedang diminta sebagai operasi atom tunggal. Sistem file memeriksa oplock sebelum melakukan operasi pembuatan, dan akan gagal membuat dengan kode pengembalian STATUS_CANNOT_BREAK_OPLOCK jika hasilnya adalah merusak oplock yang ada. Bendera ini tersedia dimulai dengan Windows 7 dan Windows Server 2008 R2.
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. Bendera ini tersedia dimulai dengan Windows 7 dan Windows Server 2008 R2.
FILE_SESSION_AWARE (0x00040000) Klien yang membuka file atau perangkat mengetahui sesi dan akses per sesi divalidasi jika perlu. Bendera ini tersedia dimulai dengan Windows 8.
FILE_RESERVE_OPFILTER (0x00100000) Bendera ini memungkinkan aplikasi untuk meminta Filter kunci oportunistik (oplock) untuk mencegah aplikasi lain mendapatkan pelanggaran berbagi. Jika sudah ada handel yang 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 pemilah 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.
FILE_CONTAINS_EXTENDED_CREATE_INFORMATION (0x10000000) Menginterpretasikan parameter EaBuffer sebagai instans EXTENDED_CREATE_INFORMATION. Bendera ini tersedia mulai dari Windows 11, versi 22H2.

[in, optional] EaBuffer

Untuk driver perangkat dan perantara, parameter ini harus berupa penunjuk NULL .

[in] EaLength

Untuk driver perangkat dan perantara, parameter ini harus nol.

Mengembalikan nilai

NtCreateFile mengembalikan STATUS_SUCCESS pada keberhasilan atau kode kesalahan NTSTATUS yang sesuai pada kegagalan. Dalam kasus terakhir, pemanggil dapat menentukan penyebab kegagalan dengan memeriksa parameter IoStatusBlock .

Catatan

NtCreateFile 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 NtCreateFile mencoba menangani situasi ini.

Keterangan

NtCreateFile menyediakan handel yang dapat digunakan pemanggil untuk memanipulasi data file, atau status dan atribut objek file. Untuk informasi selengkapnya, lihat Menggunakan File di Driver.

Setelah handel yang ditunjukkan oleh FileHandle tidak lagi digunakan, driver harus memanggil NtClose untuk menutupnya.

Jika penelepon tidak berjalan dalam konteks utas sistem, pemanggil harus memastikan bahwa setiap handel yang dibuatnya adalah handel privat. Jika tidak, handel dapat diakses oleh proses dalam konteks driver yang berjalan. Untuk informasi selengkapnya, lihat Penanganan Objek.

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

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

Mengatur bendera tertentu dalam parameter DesiredAccess menghasilkan efek berikut:

  • Agar penelepon menyinkronkan penyelesaian I/O dengan menunggu FileHandle yang dikembalikan, bendera SYNCHRONIZE harus diatur. Jika tidak, penelepon yang merupakan perangkat atau driver perantara harus menyinkronkan penyelesaian I/O dengan menggunakan objek peristiwa.
  • Jika pemanggil hanya mengatur bendera FILE_APPEND_DATA dan SYNCHRONIZE, pemanggil hanya dapat menulis ke akhir file, dan informasi offset apa pun tentang operasi tulis ke file diabaikan. File akan secara otomatis diperluas seperlunya untuk jenis operasi ini.
  • Mengatur bendera FILE_WRITE_DATA untuk file juga memungkinkan pemanggil menulis di luar akhir file. Sekali lagi, file secara otomatis diperluas seperlunya.
  • Jika penelepon hanya mengatur bendera FILE_EXECUTE dan SYNCHRONIZE, pemanggil tidak dapat langsung membaca atau menulis data apa pun ke file menggunakan FileHandle yang dikembalikan. Artinya, semua operasi pada file terjadi melalui pager sistem sebagai respons terhadap instruksi dan operasi akses data. Perangkat dan driver perantara tidak boleh mengatur bendera FILE_EXECUTE.

Parameter ShareAccess menentukan apakah utas terpisah dapat mengakses file yang sama, mungkin secara bersamaan. Asalkan kedua penelepon memiliki hak akses yang sesuai, file dapat berhasil dibuka dan dibagikan. Jika pemanggil asli NtCreateFile tidak menentukan FILE_SHARE_READ, FILE_SHARE_WRITE, atau FILE_SHARE_DELETE, tidak ada penelepon lain yang dapat membuka file—yaitu, pemanggil asli diberikan akses eksklusif.

Agar berhasil membuka file bersama, bendera DesiredAccess harus kompatibel dengan bendera DesiredAccess dan ShareAccess dari semua operasi terbuka sebelumnya yang belum dirilis melalui . Artinya, DesiredAccess yang ditentukan ke NtCreateFile untuk file tertentu tidak boleh bertentangan dengan akses yang tidak diizinkan oleh pembuka lain dari file.

Nilai CreateDisposition FILE_SUPERSEDE mengharuskan pemanggil memiliki akses DELETE ke objek file yang ada. Jika demikian, panggilan yang berhasil ke NtCreateFile 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 NtCreateFile dipanggil dengan file yang ada dan salah satu nilai CreateDisposition ini, file akan 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 NtCreateFile 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, Microsoft Windows 3.1, dan OS/2.

Nilai FILE_DIRECTORY_FILE CreateOptions menentukan bahwa file yang akan dibuat atau dibuka adalah 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 NtCreateFile akan gagal.

Bendera FILE_NO_INTERMEDIATE_BUFFERING CreateOptions mencegah sistem file melakukan buffer perantara atas nama pemanggil. Menentukan bendera ini menempatkan batasan berikut pada parameter pemanggil ke rutinitas File ZwXxx lainnya.

  • ByteOffset opsional apa pun yang diteruskan ke NtReadFile atau NtWriteFile harus berupa kelipatan ukuran sektor.
  • Panjang yang diteruskan ke NtReadFile atau NtWriteFile 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 keselarasan perangkat yang mendasar. Untuk mendapatkan informasi ini, panggil NtCreateFile untuk mendapatkan handel untuk objek file yang mewakili perangkat fisik, dan teruskan handel tersebut ke NtQueryInformationFile. Untuk daftar nilai FILE_XXX_ALIGNMENT sistem, lihat DEVICE_OBJECT.
  • Panggilan ke NtSetInformationFile dengan parameter FileInformationClass yang diatur ke FilePositionInformation harus menentukan offset yang merupakan kelipatan ukuran sektor.

Bendera FILE_SYNCHRONOUS_IO_ALERT dan FILE_SYNCHRONOUS_IO_NONALERT CreateOptions (yang saling eksklusif) menentukan bahwa semua operasi I/O pada file akan sinkron, selama operasi terjadi melalui objek file yang disebutkan oleh FileHandle yang dikembalikan. Semua I/O pada file tersebut diserialisasikan di semua utas menggunakan handel yang dikembalikan. Jika salah satu bendera CreateOptions ini diatur, bendera SYNCHRONIZE DesiredAccess juga harus diatur untuk memaksa manajer I/O menggunakan objek file sebagai objek sinkronisasi. Dalam kasus ini, manajer I/O melacak offset posisi file saat ini, yang dapat Anda teruskan ke NtReadFile dan NtWriteFile. Panggil NtQueryInformationFile atau NtSetInformationFile untuk mendapatkan atau mengatur posisi ini.

Jika bendera CreateOptions FILE_OPEN_REPARSE_POINT tidak ditentukan dan NtCreateFile 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 NtCreateFile mencoba untuk langsung membuka file titik reparse. Dalam kedua kasus, jika operasi terbuka berhasil, NtCreateFile mengembalikan STATUS_SUCCESS; jika tidak, rutinitas mengembalikan kode kesalahan NTSTATUS. NtCreateFile 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 NtCreateFile lalu meminta oplock apa pun. Ini memastikan bahwa pemilik oplock akan diberi tahu tentang permintaan terbuka berikutnya 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 FILE_OPEN_REQUIRING_OPLOCK harus meminta oplock setelah panggilan ini berhasil, atau semua upaya berikutnya untuk membuka file akan diblokir tanpa manfaat pemrosesan oplock normal. Demikian pula, jika panggilan ini berhasil tetapi permintaan oplock berikutnya 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 Filter oplock. Untuk menggunakannya, Anda harus menyelesaikan langkah-langkah berikut:

  1. 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.
  2. Jika permintaan pembuatan berhasil, minta oplock.
  3. Buka handel lain ke file untuk melakukan I/O.

Langkah 3 membuat ini praktis hanya untuk Filter oplock. 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 Level 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.

Untuk bendera createOptions FILE_OPEN_BY_FILE_ID, contoh nama perangkat akan memiliki format:

\??\C:\<FileID>
\device\HardDiskVolume1\<ObjectID>

di mana FileID adalah 8 byte dan ObjectID adalah 16 byte:

  • Pada NTFS, ini bisa berupa nomor referensi atau ID objek 8-byte atau 16-byte. Nomor referensi 16 byte sama dengan angka 8-byte yang dilapisi dengan nol.
  • Pada ReFS, ini bisa menjadi nomor referensi 8-byte atau 16-byte. Angka 16-byte tidak terkait dengan angka 8-byte. ID objek tidak didukung.
  • Sistem file FAT, ExFAT, UDFS, dan CDFS tidak mendukung bendera FILE_OPEN_BY_FILE_ID.

Jumlah ini ditetapkan oleh dan khusus untuk sistem file tertentu. Karena bidang nama file sebagian akan berisi blob biner, salah untuk mengasumsikan bahwa ini adalah string Unicode yang valid, dan yang lebih penting mungkin bukan string yang dihentikan null.

Penelepon NtCreateFile harus berjalan di IRQL = PASSIVE_LEVEL dan dengan APC kernel khusus diaktifkan.

Catatan

Jika panggilan ke fungsi ini terjadi dalam mode pengguna, Anda harus menggunakan nama "NtCreateFile" alih-alih "ZwCreateFile".

Untuk panggilan dari driver mode kernel, versi NtXxx dan ZwXxx dari rutinItas Windows Native System Services dapat berperilaku berbeda dalam cara mereka menangani dan menginterpretasikan parameter input. Untuk informasi selengkapnya tentang hubungan antara versi NtXxx dan ZwXxx dari rutinitas, lihat Menggunakan Versi Nt dan Zw dari Rutinitas Layanan Sistem Asli.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows 2000
Target Platform Universal
Header ntifs.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (lihat bagian Keterangan)
Aturan kepatuhan DDI HwStorPortProhibitedDDIs, PowerIrpDDis

Lihat juga

ACCESS_MASK

DEVICE_OBJECT

EXTENDED_CREATE_INFORMATION

IO_STATUS_BLOCK

InitializeObjectAttributes

NtClose

NtOpenFile

NtQueryInformationFile

NtReadFile

NtSetInformationFile

NtWriteFile