Fungsi NtCreateFile (winternl.h)

  • Artikel

Membuat file atau direktori baru, atau membuka file, perangkat, direktori, atau volume yang ada.

 

Fungsi ini adalah mode pengguna yang setara dengan fungsi ZwCreateFile yang didokumenkan dalam Windows Driver Kit (WDK).

Sintaks

__kernel_entry 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]           PVOID              EaBuffer,
  [in]           ULONG              EaLength
);

Parameter

[out] FileHandle

Penunjuk ke variabel yang menerima handel file jika panggilan berhasil.

[in] DesiredAccess

Nilai ACCESS_MASK yang mengekspresikan jenis akses yang diperlukan pemanggil ke file atau direktori. Kumpulan bendera DesiredAccess yang ditentukan sistem menentukan hak akses khusus berikut untuk objek file.

Nilai Makna
DELETE
 File dapat dihapus.
FILE_READ_DATA
 Data dapat dibaca dari file .
FILE_READ_ATTRIBUTES
 Bendera FileAttributes , dijelaskan nanti, dapat dibaca.
FILE_READ_EA
 Atribut yang diperluas yang terkait dengan file dapat dibaca. Bendera ini tidak relevan dengan driver perangkat dan perantara.
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
 Atribut yang diperluas (EA) yang terkait dengan file dapat ditulis. Bendera ini tidak relevan dengan driver perangkat dan perantara.
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
 FileHandle yang dikembalikan dapat ditunggu untuk disinkronkan dengan penyelesaian operasi I/O. Jika FileHandle tidak dibuka untuk I/O sinkron, nilai ini diabaikan.
FILE_EXECUTE
 Data dapat dibaca ke dalam memori dari file menggunakan I/O halaman sistem. Bendera ini tidak relevan untuk driver perangkat dan perantara.
 

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

Pemanggil NtCreateFile dapat menentukan satu atau kombinasi dari yang berikut ini, mungkin menggunakan bitwise-OR dengan bendera kompatibel tambahan dari daftar bendera DesiredAccess sebelumnya, untuk objek file apa pun yang tidak mewakili file direktori.

Nilai Makna
FILE_GENERIC_READ
 STANDARD_RIGHTS_READ | FILE_READ_DATA | FILE_READ_ATTRIBUTES | FILE_READ_EA | SYNCHRONIZE
FILE_GENERIC_WRITE
 STANDARD_RIGHTS_WRITE | FILE_WRITE_DATA | FILE_WRITE_ATTRIBUTES | FILE_WRITE_EA | FILE_APPEND_DATA | SYNCHRONIZE
FILE_GENERIC_EXECUTE
 STANDARD_RIGHTS_EXECUTE | FILE_READ_ATTRIBUTES | FILE_EXECUTE | SYNCHRONIZE
 

Nilai FILE_GENERIC_EXECUTE tidak relevan untuk perangkat dan driver perantara.

STANDARD_RIGHTS_XXX adalah nilai sistem yang telah ditentukan sebelumnya yang digunakan untuk menegakkan keamanan pada objek sistem.

Untuk membuka atau membuat file direktori, seperti yang juga ditunjukkan dengan parameter CreateOptions , pemanggil NtCreateFile dapat menentukan satu atau kombinasi dari yang berikut ini, mungkin menggunakan bitwise-OR dengan satu atau beberapa bendera yang kompatibel dari daftar bendera DesiredAccess sebelumnya.

Nilai Makna
FILE_LIST_DIRECTORY
 File dalam direktori dapat dicantumkan.
FILE_TRAVERSE
 Direktori dapat dilalui: yaitu, dapat menjadi bagian dari nama jalur file.

[in] ObjectAttributes

Penunjuk ke struktur yang sudah diinisialisasi dengan InitializeObjectAttributes. Anggota struktur ini untuk objek file mencakup yang berikut ini.

Nilai Makna
Panjang ULONG
 Menentukan jumlah byte data ObjectAttributes yang disediakan. Nilai ini harus setidaknya ukuranof(OBJECT_ATTRIBUTES).
HANDLE RootDirectory
 Secara opsional menentukan handel ke direktori yang diperoleh oleh panggilan sebelumnya ke NtCreateFile. 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.
PUNICODE_STRING ObjectName
 Menunjuk ke string Unicode buffer yang menamai file yang akan dibuat atau dibuka. Nilai ini harus merupakan spesifikasi file yang sepenuhnya memenuhi syarat atau nama objek perangkat, 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, asalkan driver floppy dan sistem file yang terlalu besar sudah dimuat. Untuk informasi selengkapnya, lihat Nama File, Jalur, dan Namespace.
Atribut ULONG
 Adalah sekumpulan bendera yang mengontrol atribut objek file. Nilai ini bisa nol atau OBJ_CASE_INSENSITIVE, yang menunjukkan bahwa kode pencarian nama harus mengabaikan kasus anggota ObjectName daripada melakukan pencarian yang sama persis. Nilai OBJ_INHERIT tidak relevan dengan driver perangkat dan perantara.
PSECURITY_DESCRIPTOR SecurityDescriptor
 Secara opsional menentukan deskriptor keamanan yang akan diterapkan ke file. ACL yang ditentukan oleh deskriptor keamanan tersebut diterapkan ke file hanya ketika 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. Perangkat dan driver perantara dapat mengatur anggota ini ke NULL.
PSECURITY_QUALITY_OF_SERVICE SecurityQualityOfService
 Menentukan hak akses yang harus diberikan server ke konteks keamanan klien. Nilai ini bukan-NULL hanya ketika koneksi ke server yang dilindungi dibuat, memungkinkan pemanggil untuk mengontrol bagian mana dari konteks keamanan pemanggil yang tersedia untuk server dan apakah server diizinkan untuk meniru pemanggil.

[out] IoStatusBlock

Pointer ke variabel yang menerima status penyelesaian akhir dan informasi tentang operasi yang diminta. Saat kembali dari NtCreateFile, anggota Informasi berisi salah satu nilai berikut ini:

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

[in, optional] AllocationSize

Ukuran alokasi awal dalam byte untuk file. Nilai bukan nol tidak berpengaruh kecuali file sedang dibuat, ditimpa, atau digantikan.

[in] FileAttributes

Atribut file. Atribut yang ditentukan secara eksplisit hanya diterapkan saat file dibuat, digantikan, atau, dalam beberapa kasus, ditimpa. Secara default, nilai ini adalah FILE_ATTRIBUTE_NORMAL, yang dapat ditimpa oleh kombinasi ORed dari satu atau beberapa bendera FILE_ATTRIBUTE_xxxx , yang didefinisikan dalam Wdm.h dan NtDdk.h. Untuk daftar bendera yang dapat digunakan dengan NtCreateFile, lihat CreateFile.

[in] ShareAccess

Jenis akses berbagi yang ingin digunakan pemanggil dalam file, sebagai nol, atau sebagai salah satu atau kombinasi dari nilai berikut.

Nilai Makna
FILE_SHARE_READ
 File dapat dibuka untuk akses baca oleh panggilan utas lain ke NtCreateFile.
FILE_SHARE_WRITE
 File dapat dibuka untuk akses tulis oleh panggilan utas lain ke NtCreateFile.
FILE_SHARE_DELETE
 File dapat dibuka untuk menghapus akses dengan panggilan utas lain ke NtCreateFile.
 

Untuk informasi selengkapnya, lihat Windows SDK.

[in] CreateDisposition

Menentukan apa yang harus dilakukan, bergantung pada apakah file sudah ada, sebagai salah satu nilai berikut.

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

[in] CreateOptions

Opsi yang akan diterapkan saat membuat atau membuka file, sebagai kombinasi yang kompatibel dari bendera berikut.

Nilai Makna
FILE_DIRECTORY_FILE
 File yang sedang dibuat atau dibuka adalah file direktori. Dengan bendera ini, parameter CreateDisposition harus diatur ke FILE_CREATE, FILE_OPEN, atau FILE_OPEN_IF. Dengan bendera ini, bendera CreateOptions lain yang kompatibel hanya mencakup yang berikut ini: FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO _NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT, dan FILE_OPEN_BY_FILE_ID.
FILE_NON_DIRECTORY_FILE
 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_WRITE_THROUGH
 Aplikasi yang menulis data ke file harus benar-benar mentransfer data ke dalam file sebelum operasi tulis yang diminta dianggap selesai. Bendera ini secara otomatis diatur jika bendera CreateOptionsFILE_NO_INTERMEDIATE _BUFFERING diatur.
FILE_SEQUENTIAL_ONLY
 Semua akses ke file berurutan.
FILE_RANDOM_ACCESS
 Akses ke file bisa acak, jadi tidak ada operasi read-ahead berurutan yang harus dilakukan pada file oleh FSD atau sistem.
FILE_NO_INTERMEDIATE_BUFFERING
 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
 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 DesiredAccessSYNCHRONIZE juga harus diatur.
FILE_SYNCHRONOUS_IO_NONALERT
 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 DesiredAccessSYNCHRONIZE juga harus diatur.
FILE_CREATE_TREE_CONNECTION
 Buat koneksi pohon untuk file ini untuk membukanya melalui jaringan. Bendera ini tidak digunakan oleh perangkat dan driver perantara.
FILE_NO_EA_KNOWLEDGE
 Jika atribut yang diperluas pada file yang ada dibuka menunjukkan bahwa pemanggil harus memahami EA untuk menginterpretasikan file dengan benar, gagalkan permintaan ini karena pemanggil tidak memahami cara menangani EA. Bendera ini tidak relevan untuk perangkat dan driver perantara.
FILE_OPEN_REPARSE_POINT
 Buka file dengan titik pemisahan ulang dan lewati pemrosesan titik pemilah ulang normal untuk file. Untuk informasi lebih lanjut, lihat bagian Keterangan.
FILE_DELETE_ON_CLOSE
 Hapus file ketika handel terakhir diteruskan ke NtClose. Jika bendera ini diatur, bendera DELETE harus diatur dalam parameter DesiredAccess .
FILE_OPEN_BY_FILE_ID
 Nama file yang ditentukan oleh parameter ObjectAttributes menyertakan nomor referensi file 8-byte untuk file tersebut. Jumlah ini ditetapkan oleh dan khusus untuk sistem file tertentu. Jika file adalah titik pemisahan ulang, nama file juga akan menyertakan nama perangkat. Perhatikan bahwa sistem file FAT tidak mendukung bendera ini. Bendera ini tidak digunakan oleh perangkat dan driver perantara.
FILE_OPEN_FOR_BACKUP_INTENT
 File sedang dibuka untuk niat pencadangan. Oleh karena itu, sistem harus memeriksa hak akses tertentu dan memberi pemanggil akses yang sesuai ke file sebelum memeriksa parameter DesiredAccess terhadap deskriptor keamanan file. Bendera ini tidak digunakan oleh perangkat dan driver perantara.
FILE_RESERVE_OPFILTER
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 lebih lanjut, lihat bagian Keterangan.
FILE_OPEN_REQUIRING_OPLOCK
 File sedang dibuka dan kunci oportunistik (oplock) pada file 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. Untuk informasi selengkapnya, lihat bagian Keterangan. Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Bendera ini tidak didukung.

Bendera ini didukung pada sistem file berikut: NTFS, FAT, dan exFAT.
FILE_COMPLETE_IF_OPLOCKED
 Selesaikan operasi ini segera dengan kode keberhasilan alternatif STATUS_OPLOCK_BREAK_IN_PROGRESS jika file target di-oplock, daripada memblokir utas penelepon. Jika file di-oplock, penelepon lain sudah memiliki akses ke file. Bendera ini tidak digunakan oleh perangkat dan driver perantara.

[in] EaBuffer

Penunjuk ke buffer EA yang digunakan untuk meneruskan atribut yang diperluas.

Catatan Beberapa sistem file mungkin tidak mendukung buffer EA.
 

[in] EaLength

Panjang buffer EA.

Mengembalikan nilai

NtCreateFile mengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai. Jika mengembalikan status kesalahan, pemanggil dapat menemukan informasi selengkapnya tentang penyebab kegagalan dengan memeriksa IoStatusBlock. Untuk menyederhanakan pemeriksaan ini, aplikasi dapat menggunakan makro NT_SUCCESS, NT_ERROR, dan NT_WARNING .

Keterangan

Handel, yang diberikan oleh NtCreateFile, dapat digunakan oleh panggilan berikutnya untuk memanipulasi data dalam file atau status atau atribut objek file.

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
Bendera DesiredAccess tertentu dan kombinasi bendera memiliki efek berikut:
  • Agar penelepon menyinkronkan penyelesaian I/O dengan menunggu FileHandle yang dikembalikan, bendera SYNCHRONIZE harus diatur.
  • Meneruskan nol ke DesiredFlags tidak valid.
  • 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.
  • 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.
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 NtCreateFile tidak menentukan FILE_SHARE_READ, FILE_SHARE_WRITE, atau FILE_SHARE_DELETE, tidak ada operasi terbuka lain yang dapat dilakukan pada file; artinya, penelepon asli diberikan akses eksklusif ke file.

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

Nilai CreateDispositionFILE_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 CreateDispositionFILE_OVERWRITE_IF dan FILE_SUPERSEDE serupa. Jika ZwCreateFile 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 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 sistem operasi 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 NtCreateFile gagal.

Bendera CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING mencegah sistem file melakukan buffer perantara atas nama pemanggil. Menentukan nilai ini menempatkan batasan tertentu pada parameter pemanggil ke rutinitas File NtXXX lainnya, termasuk yang berikut ini:

  • Setiap ByteOffset opsional yang diteruskan ke fungsi NtReadFile atau NtWriteFile harus merupakan integral dari 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 disesuaikan sesuai dengan persyaratan penyelarasan perangkat yang mendasar. Informasi ini dapat diperoleh dengan memanggil NtCreateFile untuk mendapatkan handel untuk objek file yang mewakili perangkat fisik, lalu memanggil NtQueryInformationFile dengan handel tersebut. Untuk daftar sistem FILE_XXX_ALIGNMENT nilai, lihat dokumentasi Windows SDK.
  • Panggilan ke NtSetInformationFile dengan parameter FileInformationClass yang diatur ke FilePositionInformation harus menentukan offset yang merupakan integral dari ukuran sektor.
Bendera CreateOptionsFILE_SYNCHRONOUS_IO_ALERT dan FILE_SYNCHRONOUS_IO_NONALERT , yang saling eksklusif seperti namanya, tentukan bahwa semua operasi I/O pada file harus sinkron selama terjadi melalui objek file yang disebutkan oleh FileHandle yang dikembalikan. Semua I/O pada file tersebut diserialisasikan di semua utas menggunakan handel yang dikembalikan. Dengan salah satu CreateOptions ini, bendera DesiredAccessSYNCHRONIZE harus diatur sehingga Manajer I/O menggunakan objek file sebagai objek sinkronisasi. Dengan salah satu dari set CreateOptions ini, Manajer I/O mempertahankan "konteks posisi file" untuk objek file, offset posisi file internal saat ini. Offset ini dapat digunakan dalam panggilan ke NtReadFile dan NtWriteFile. Posisinya juga dapat dikueri atau diatur dengan NtQueryInformationFile dan NtSetInformationFile.

Jika parameter CreateOptions menentukan bendera FILE_OPEN_REPARSE_POINT dan NtCreateFile membuka file dengan titik reparse, pemrosesan pemilah ulang normal tidak terjadi dan NtCreateFile mencoba untuk langsung membuka file titik pemilah ulang. Jika bendera FILE_OPEN_REPARSE_POINT tidak ditentukan, pemrosesan titik pemilah ulang normal terjadi untuk file. Dalam kedua kasus, jika operasi terbuka berhasil, NtCreateFile mengembalikan STATUS_SUCCESS; jika tidak, kode kesalahan. Fungsi NtCreateFile tidak pernah mengembalikan STATUS_REPARSE.

Bendera FILE_OPEN_REQUIRING_OPLOCK parameter CreateOptions menghilangkan waktu antara saat Anda membuka file dan meminta oplock yang berpotensi memungkinkan pihak ketiga untuk membuka file, yang akan menyebabkan pelanggaran berbagi. Aplikasi dapat menggunakan bendera FILE_OPEN_REQUIRING_OPLOCK dengan 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 ini, 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 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 yang lebih baru untuk sistem file berikut: NTFS, FAT, dan exFAT.
 

Bendera FILE_RESERVE_OPFILTER parameter CreateOptions memungkinkan aplikasi untuk meminta oplock Tingkat 1, Batch, atau Filter untuk mencegah aplikasi lain mendapatkan pelanggaran berbagi. Namun, dalam istilah praktis, FILE_RESERVE_OPFILTER hanya berguna untuk oplock filter. Untuk menggunakannya, Anda harus menyelesaikan langkah-langkah berikut:

  1. Terbitkan permintaan buat dengan CreateOptionsFILE_RESERVE_OPFILTER, DesiredAccess dari FILE_READ_ATTRIBUTES, dan ShareAccess persis (FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE). Kemungkinan kegagalan adalah sebagai berikut:
    • Jika sudah ada handel terbuka, permintaan buat gagal dengan STATUS_OPLOCK_NOT_GRANTED, dan oplock berikutnya yang diminta juga gagal.
    • Jika Anda membuka dengan lebih banyak akses daripada berbagi FILE_READ_ATTRIBUTES atau kurang dari (FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE), permintaan gagal dengan STATUS_OPLOCK_NOT_GRANTED.
  2. Jika permintaan pembuatan berhasil, minta oplock.
  3. Buka handel lain ke file untuk melakukan I/O.
Langkah ketiga membuat ini praktis hanya untuk oplock filter. Handel yang dibuka pada langkah ketiga dapat memiliki DesiredAccess yang berisi maksimum (FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL) dan masih tidak merusak oplock filter. Namun, setiap DesiredAccess 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 informasi selengkapnya tentang oplock, lihat Oplock Semantics.

Perhatikan bahwa file header WDK NtDef.h diperlukan untuk banyak definisi konstan serta makro InitializeObjectAttributes . Anda juga dapat menggunakan fungsi LoadLibrary dan GetProcAddress untuk menautkan secara dinamis ke NtDll.dll.

Persyaratan

Persyaratan Nilai
Target Platform Windows
Header winternl.h
Pustaka ntdll.lib
DLL ntdll.dll