struktur CREATEFILE2_EXTENDED_PARAMETERS (fileapi.h)
Berisi parameter opsional yang diperluas untuk CreateFile2.
Sintaks
typedef struct _CREATEFILE2_EXTENDED_PARAMETERS {
DWORD dwSize;
DWORD dwFileAttributes;
DWORD dwFileFlags;
DWORD dwSecurityQosFlags;
LPSECURITY_ATTRIBUTES lpSecurityAttributes;
HANDLE hTemplateFile;
} CREATEFILE2_EXTENDED_PARAMETERS, *PCREATEFILE2_EXTENDED_PARAMETERS, *LPCREATEFILE2_EXTENDED_PARAMETERS;
Anggota
dwSize
Berisi ukuran struktur ini, sizeof(CREATEFILE2_EXTENDED_PARAMETERS).
dwFileAttributes
Atribut dan bendera file atau perangkat, FILE_ATTRIBUTE_NORMAL menjadi nilai default yang paling umum untuk file.
Parameter ini dapat mencakup kombinasi atribut file yang tersedia (FILE_ATTRIBUTE_*). Semua atribut file lainnya mengambil alih FILE_ATTRIBUTE_NORMAL.
Catatan
Ketika CreateFile2 membuka file yang ada, umumnya menggabungkan bendera file dengan atribut file dari file yang ada, dan mengabaikan atribut file apa pun yang disediakan sebagai bagian dari dwFlagsAndAttributes. Kasus khusus dirinci dalam Membuat dan Membuka File.
Beberapa atribut dan bendera file berikut mungkin hanya berlaku untuk file dan belum tentu semua jenis perangkat lain yang dapat dibuka CreateFile2 . Untuk informasi tambahan, lihat bagian Keterangan dari CreateFile2 halaman referensi dan Membuat dan Membuka File.
Untuk akses tingkat lanjut lainnya ke atribut file, lihat SetFileAttributes. Untuk daftar lengkap semua atribut file dengan nilai dan deskripsinya, lihat Konstanta Atribut File.
| Atribut | Makna |
|---|---|
|
File harus diarsipkan. Aplikasi menggunakan atribut ini untuk menandai file untuk pencadangan atau penghapusan. |
|
File atau direktori dienkripsi. Untuk file, ini berarti bahwa semua data dalam file dienkripsi. Untuk direktori, ini berarti bahwa enkripsi adalah default untuk file dan subdirektori yang baru dibuat. Untuk informasi selengkapnya, lihat Enkripsi File.
Bendera ini tidak berpengaruh jika FILE_ATTRIBUTE_SYSTEM juga ditentukan. Bendera ini tidak didukung pada Windows edisi Home, Home Premium, Starter, atau ARM. Bendera ini tidak didukung ketika dipanggil dari aplikasi Bursa Windows. |
|
File disembunyikan. Jangan sertakan dalam daftar direktori biasa. |
|
File atau direktori yang dikonfigurasi dengan integritas. Untuk file, semua aliran data dalam file memiliki integritas. Untuk direktori, integritas adalah default untuk file dan subdirektori yang baru dibuat, kecuali pemanggil menentukan sebaliknya.
Bendera ini hanya didukung pada sistem file ReFS. |
|
File tidak memiliki atribut lain yang ditetapkan. Atribut ini hanya valid jika digunakan sendiri. |
|
Data file tidak segera tersedia. Atribut ini menunjukkan bahwa data file dipindahkan secara fisik ke penyimpanan offline. Atribut ini digunakan oleh Remote Storage, perangkat lunak manajemen penyimpanan hierarkis. Aplikasi tidak boleh secara segan mengubah atribut ini. |
|
File hanya dapat dibaca. Aplikasi dapat membaca file, tetapi tidak dapat menulis atau menghapusnya. |
|
File adalah bagian dari atau digunakan secara eksklusif oleh sistem operasi. |
|
File sedang digunakan untuk penyimpanan sementara.
Untuk informasi selengkapnya, lihat bagian Perilaku Penembolokan dari topik ini. |
dwFileFlags
Parameter ini dapat berisi kombinasi bendera (FILE_FLAG_*) untuk kontrol perilaku penembolokan file atau perangkat, mode akses, dan bendera tujuan khusus lainnya.
| Bendera | Makna |
|---|---|
|
File sedang dibuka atau dibuat untuk operasi pencadangan atau pemulihan. Sistem memastikan bahwa proses panggilan mengambil alih pemeriksaan keamanan file ketika proses memiliki hak istimewa SE_BACKUP_NAME dan SE_RESTORE_NAME . Untuk informasi selengkapnya, lihat Mengubah Hak Istimewa dalam Token.
Anda harus mengatur bendera ini untuk mendapatkan handel ke direktori. Handel direktori dapat diteruskan ke beberapa fungsi alih-alih handel file. Untuk informasi lebih lanjut, lihat bagian Keterangan. |
|
File akan dihapus segera setelah semua pegangannya ditutup, yang mana mencakup pegangan yang ditentukan dan pegangan lain yang terbuka atau yang diduplikasi.
Jika ada handel terbuka yang ada ke file, panggilan gagal kecuali semuanya dibuka dengan mode berbagi FILE_SHARE_DELETE . Permintaan terbuka berikutnya untuk file tersebut akan gagal, kecuali mode berbagi FILE_SHARE_DELETE ditentukan. |
|
Peta perangkat adalah pemetaan antara nama perangkat DOS dan perangkat dalam sistem, dan digunakan saat menyelesaikan nama DOS. Peta perangkat terpisah ada untuk setiap pengguna dalam sistem, dan pengguna dapat mengelola peta perangkat mereka sendiri. Biasanya selama peniruan identitas, peta perangkat pengguna yang ditiru akan digunakan. Namun, ketika bendera ini diatur, peta perangkat pengguna proses digunakan sebagai gantinya. |
|
File atau perangkat sedang dibuka tanpa penembolokan sistem untuk pembacaan dan penulisan data. Bendera ini tidak mempengaruhi penembolokan hard disk atau file yang dipetakan memori.
Ada persyaratan ketat untuk berhasil bekerja dengan file yang dibuka dengan CreateFile2 menggunakan bendera FILE_FLAG_NO_BUFFERING , untuk detailnya lihat Buffering File. |
|
Data file diminta, tetapi harus terus berada di penyimpanan jarak jauh. Ini tidak boleh diangkut kembali ke penyimpanan lokal. Bendera ini untuk digunakan oleh sistem penyimpanan jarak jauh. |
|
Pemrosesan titik pemisahan ulang normal tidak akan terjadi; CreateFile2 akan mencoba membuka titik pemilah ulang. Saat file dibuka, handel file dikembalikan, apakah filter yang mengontrol titik pemisahan ulang beroperasi atau tidak.
Bendera ini tidak dapat digunakan dengan bendera CREATE_ALWAYS . Jika file bukan titik pemilah ulang, maka bendera ini diabaikan. Untuk informasi lebih lanjut, lihat bagian Keterangan. |
|
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 kesalahan terakhir ERROR_CANNOT_BREAK_OPLOCK jika hasilnya akan merusak oplock yang ada.
Jika Anda menggunakan bendera ini dan panggilan Anda ke fungsi CreateFile2 berhasil kembali, operasi pertama yang harus Anda lakukan pada handel file adalah meminta oplock dengan memanggil fungsi DeviceIOControl dan kemudian meneruskan FSCTL_REQUEST_OPLOCK atau salah satu Operasi Penguncian Opportunistik lainnya. Jika Anda melakukan operasi sistem file lain dengan handel file sebelum meminta oplock, kebuntuan mungkin terjadi. Catatan Anda dapat dengan aman memanggil fungsi CloseHandle pada handel file tanpa terlebih dahulu meminta oplock.
|
|
File atau perangkat sedang dibuka atau dibuat untuk I/O asinkron.
Ketika operasi I/O berikutnya selesai pada handel ini, peristiwa yang ditentukan dalam struktur TUMPANG TINDIH akan diatur ke status yang disinyalir. Jika bendera ini ditentukan, file dapat digunakan untuk operasi baca dan tulis secara bersamaan. Jika bendera ini tidak ditentukan, maka operasi I/O diserialisasikan, bahkan jika panggilan ke fungsi baca dan tulis menentukan struktur YANG TUMPANG TINDIH . Untuk informasi tentang pertimbangan saat menggunakan handel file yang dibuat dengan bendera ini, lihat bagian Handel I/O Sinkron dan Asinkron dari topik ini. |
|
Akses akan terjadi sesuai dengan aturan POSIX. Ini termasuk mengizinkan beberapa file dengan nama, hanya berbeda jika, untuk sistem file yang mendukung penamaan tersebut. Gunakan perawatan saat menggunakan opsi ini, karena file yang dibuat dengan bendera ini mungkin tidak dapat diakses oleh aplikasi yang ditulis untuk MS-DOS atau Windows 16-bit. |
|
Akses dimaksudkan untuk acak. Sistem dapat menggunakan ini sebagai petunjuk untuk mengoptimalkan penembolokan file.
Bendera ini tidak berpengaruh jika sistem file tidak mendukung I/O cache dan FILE_FLAG_NO_BUFFERING. Untuk informasi selengkapnya, lihat bagian Perilaku Penembolokan dari topik ini. |
|
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.
Windows Server 2008 R2 dan Windows Server 2008: Bendera ini tidak didukung sebelum Windows Server 2012. |
|
Akses dimaksudkan untuk berurutan dari awal hingga akhir. Sistem dapat menggunakan ini sebagai petunjuk untuk mengoptimalkan penembolokan file.
Bendera ini tidak boleh digunakan jika read-behind (yaitu, pemindaian mundur) akan digunakan. Bendera ini tidak berpengaruh jika sistem file tidak mendukung I/O cache dan FILE_FLAG_NO_BUFFERING. Untuk informasi selengkapnya, lihat bagian Perilaku Penembolokan dari topik ini. |
|
Operasi tulis tidak akan melalui cache perantara apa pun, mereka akan langsung masuk ke disk.
Untuk informasi tambahan, lihat bagian Perilaku Penembolokan dari topik ini. |
dwSecurityQosFlags
Parameter dwSecurityQosFlags menentukan informasi SQOS. Untuk informasi selengkapnya, lihat Tingkat Peniruan.
lpSecurityAttributes
Penunjuk ke struktur SECURITY_ATTRIBUTES yang berisi dua anggota data terpisah tetapi terkait: deskriptor keamanan opsional, dan nilai Boolean yang menentukan apakah handel yang dikembalikan dapat diwariskan oleh proses turunan.
Parameter ini bisa NULL.
Jika parameter ini NULL, handel yang dikembalikan oleh CreateFile2 tidak dapat diwariskan oleh proses turunan apa pun yang dapat dibuat aplikasi dan file atau perangkat yang terkait dengan handel yang dikembalikan mendapatkan pendeskripsi keamanan default.
Anggota lpSecurityDescriptor dari struktur menentukan SECURITY_DESCRIPTOR untuk file atau perangkat. Jika anggota ini NULL, file atau perangkat yang terkait dengan handel yang dikembalikan diberi pendeskripsi keamanan default.
CreateFile2 mengabaikan anggota lpSecurityDescriptor saat membuka file atau perangkat yang ada, tetapi terus menggunakan anggota bInheritHandle .
Anggota bInheritHandle dari struktur menentukan apakah handel yang dikembalikan dapat diwariskan.
Untuk informasi selengkapnya, lihat bagian Keterangan dari topik CreateFile2 .
hTemplateFile
Handel yang valid ke file templat dengan hak akses GENERIC_READ . File templat menyediakan atribut file dan atribut yang diperluas untuk file yang sedang dibuat.
Parameter ini bisa NULL.
Saat membuka file yang ada, CreateFile2 mengabaikan parameter ini.
Saat membuka file terenkripsi baru, file mewarisi daftar kontrol akses diskresi dari direktori induknya. Untuk informasi tambahan, lihat Enkripsi File.
Keterangan
Untuk mengkompilasi aplikasi yang menggunakan struktur CREATEFILE2_EXTENDED_PARAMETERS , tentukan makro _WIN32_WINNT sebagai 0x0602 atau yang lebih baru. Untuk informasi selengkapnya, lihat Menggunakan Header Windows.
Perilaku Penembolokan
Beberapa nilai yang mungkin untuk anggota dwFileFlags digunakan untuk mengontrol atau memengaruhi bagaimana data yang terkait dengan handel di-cache oleh sistem. Topologi tersebut adalah:
- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
Jika tidak ada bendera ini yang ditentukan, sistem menggunakan skema penembolokan tujuan umum default. Jika tidak, penembolokan sistem berperilaku seperti yang ditentukan untuk setiap bendera.
Beberapa bendera ini tidak boleh digabungkan. Misalnya, menggabungkan FILE_FLAG_RANDOM_ACCESS dengan FILE_FLAG_SEQUENTIAL_SCAN adalah mengalahkan diri sendiri.
Menentukan bendera FILE_FLAG_SEQUENTIAL_SCAN dapat meningkatkan performa untuk aplikasi yang membaca file besar menggunakan akses berurutan. Perolehan performa bisa lebih terlihat untuk aplikasi yang membaca file besar sebagian besar secara berurutan, tetapi kadang-kadang melewati rentang kecil byte. Jika aplikasi memindahkan penunjuk file untuk akses acak, performa penembolokan optimal kemungkinan besar tidak akan terjadi. Namun, operasi yang benar masih dijamin.
Bendera FILE_FLAG_WRITE_THROUGH dan FILE_FLAG_NO_BUFFERING independen dan dapat digabungkan.
Jika FILE_FLAG_WRITE_THROUGH digunakan tetapi FILE_FLAG_NO_BUFFERING tidak juga ditentukan, sehingga penembolokan sistem berlaku, maka data ditulis ke cache sistem tetapi dibersihkan ke disk tanpa penundaan.
Jika FILE_FLAG_WRITE_THROUGH dan FILE_FLAG_NO_BUFFERING ditentukan, sehingga penembolokan sistem tidak berlaku, maka data segera dibersihkan ke disk tanpa melalui cache sistem Windows. Sistem operasi juga meminta penulisan cache perangkat keras lokal hard disk ke media persisten.
Catatan
Tidak semua perangkat keras hard disk mendukung kemampuan write-through ini.
Penggunaan bendera FILE_FLAG_NO_BUFFERING yang tepat memerlukan pertimbangan aplikasi khusus. Untuk informasi selengkapnya, lihat Buffering File.
Permintaan write-through melalui FILE_FLAG_WRITE_THROUGH juga menyebabkan NTFS membersihkan perubahan metadata apa pun, seperti pembaruan stempel waktu atau operasi penggantian nama, yang dihasilkan dari pemrosesan permintaan. Untuk alasan ini, bendera FILE_FLAG_WRITE_THROUGH sering digunakan dengan bendera FILE_FLAG_NO_BUFFERING sebagai pengganti untuk memanggil fungsi FlushFileBuffers setelah setiap penulisan, yang dapat menyebabkan penalti performa yang tidak perlu. Menggunakan bendera ini bersama-sama menghindari penalti tersebut. Untuk informasi umum tentang penembolokan file dan metadata, lihat Penembolokan File.
Ketika FILE_FLAG_NO_BUFFERING dikombinasikan dengan FILE_FLAG_OVERLAPPED, bendera memberikan performa asinkron maksimum, karena I/O tidak bergantung pada operasi sinkron manajer memori. Namun, beberapa operasi I/O membutuhkan lebih banyak waktu, karena data tidak ditahan di cache. Selain itu, metadata file mungkin masih di-cache (misalnya, saat membuat file kosong). Untuk memastikan bahwa metadata dibersihkan ke disk, gunakan fungsi FlushFileBuffers .
Menentukan atribut FILE_ATTRIBUTE_TEMPORARY menyebabkan sistem file menghindari penulisan data kembali ke penyimpanan massal jika memori cache yang memadai tersedia, karena aplikasi menghapus file sementara setelah handel ditutup. Dalam hal ini, sistem dapat sepenuhnya menghindari penulisan data. Meskipun tidak secara langsung mengontrol penembolokan data dengan cara yang sama seperti bendera yang disebutkan sebelumnya, atribut FILE_ATTRIBUTE_TEMPORARY memang memberi tahu sistem untuk menahan sebanyak mungkin dalam cache sistem tanpa menulis dan oleh karena itu mungkin menjadi perhatian untuk aplikasi tertentu.
Handel I/O Sinkron dan Asinkron
CreateFile2 menyediakan untuk membuat handel file atau perangkat yang sinkron atau asinkron. Handel sinkron berperilaku sedemikian ruf sehingga panggilan fungsi I/O menggunakan handel tersebut diblokir sampai selesai, sementara handel file asinkron memungkinkan sistem untuk segera kembali dari panggilan fungsi I/O, apakah mereka menyelesaikan operasi I/O atau tidak. Seperti yang dinyatakan sebelumnya, perilaku sinkron versus asinkron ini ditentukan dengan menentukan FILE_FLAG_OVERLAPPED dalam anggota dwFileFlags dari struktur CREATEFILE2_EXTENDED_PARAMETERS yang diteruskan dalam parameter pCreateExParams . Ada beberapa kompleksitas dan potensi jebakan saat menggunakan I/O asinkron; untuk informasi selengkapnya, lihat I/O Sinkron dan Asinkron.
Persyaratan
| Klien minimum yang didukung | Windows 8 [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2012 [aplikasi desktop | Aplikasi UWP] |
| Header | fileapi.h (sertakan Windows.h) |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk