struktur CREATEFILE2_EXTENDED_PARAMETERS (fileapi.h)

Berisi parameter opsional yang diperluas untuk CreateFile2.

Sintaksis

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.

Nota

Ketika CreateFile2 membuka file yang ada, biasanya 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 hanya dapat berlaku untuk file dan belum tentu semua jenis perangkat lain yang CreateFile2 dapat terbuka. Untuk informasi tambahan, lihat bagian Keterangan dari halaman referensi dan Membuat dan Membuka File.

Untuk akses lebih lanjut ke atribut file, lihat SetFileAttributes. Untuk daftar lengkap semua atribut file dengan nilai dan deskripsinya, lihat Konstanta Atribut File.

Atribut	Arti
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	File harus diarsipkan. Aplikasi menggunakan atribut ini untuk menandai file untuk pencadangan atau penghapusan.
FILE_ATTRIBUTE_ENCRYPTED 16384 (0x4000)	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, lihatEnkripsi 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 saat dipanggil dari aplikasi Windows Store.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	File disembunyikan. Jangan sertakan dalam daftar direktori biasa.
FILE_ATTRIBUTE_INTEGRITY_STREAM 32768 (0x8000)	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_ATTRIBUTE_NORMAL 128 (0x80)	File tidak memiliki atribut lain yang ditetapkan. Atribut ini hanya valid jika digunakan sendiri.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	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-segan mengubah atribut ini.
FILE_ATTRIBUTE_READONLY 1 (0x1)	File hanya dibaca. Aplikasi dapat membaca file, tetapi tidak dapat menulis ke atau menghapusnya.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	File adalah bagian dari atau digunakan secara eksklusif oleh sistem operasi.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	File sedang digunakan untuk penyimpanan sementara. Untuk informasi selengkapnya, lihat bagian Perilaku Penembolokan 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	Arti
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	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 selengkapnya, lihat bagian Keterangan.
FILE_FLAG_DELETE_ON_CLOSE 0x04000000	File akan dihapus segera setelah semua handelnya ditutup, yang mencakup handel yang ditentukan dan handel terbuka atau duplikat lainnya. Jika ada handel terbuka yang ada ke file, panggilan gagal kecuali semuanya dibuka dengan mode berbagi FILE_SHARE_DELETE. Permintaan terbuka berikutnya untuk file gagal, kecuali mode berbagi FILE_SHARE_DELETE ditentukan.
FILE_FLAG_IGNORE_IMPERSONATED_DEVICEMAP 0x00020000	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, peta perangkat pengguna yang ditiru akan digunakan. Namun, ketika bendera ini diatur, peta perangkat pengguna proses digunakan sebagai gantinya.
FILE_FLAG_NO_BUFFERING 0x20000000	File atau perangkat sedang dibuka tanpa penembolokan sistem untuk pembacaan dan penulisan data. Bendera ini tidak memengaruhi 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 File Buffering.
FILE_FLAG_OPEN_NO_RECALL 0x00100000	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.
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	Pemrosesan titik pemisahan ulang normal tidak akan terjadi; CreateFile2 akan mencoba membuka titik pemilah ulang. Ketika 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 pemisahan ulang, maka bendera ini diabaikan. Untuk informasi selengkapnya, lihat bagian Keterangan.
FILE_FLAG_OPEN_REQUIRING_OPLOCK 0x00040000	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 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 dikembalikan, Anda harus meminta oplock pada file dengan memanggil DeviceIoControl pada handel file baru dengan FSCTL_REQUEST_OPLOCK atau salah satu operasi penguncian Oportunistik lainnya. Jika Anda melakukan operasi sistem file lain pada file sebelum meminta oplock, kebuntuan dapat terjadi. Kebuntuan sangat mungkin terjadi jika Anda memanggil API sistem file yang mengambil nama file daripada handel, seperti GetFileAttributes. Catatan: Anda dapat dengan aman memanggil fungsi CloseHandle pada handel file tanpa terlebih dahulu meminta oplock.
FILE_FLAG_OVERLAPPED 0x40000000	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 bersamaan. Jika bendera ini tidak ditentukan, maka operasi I/O diserialisasikan, bahkan jika panggilan ke fungsi baca dan tulis menentukan struktur TUMPANG TINDIH. Untuk informasi tentang pertimbangan saat menggunakan handel file yang dibuat dengan bendera ini, lihat bagian Handle I/O Sinkron dan Asinkron topik ini.
FILE_FLAG_POSIX_SEMANTICS 0x01000000	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 hati-hati 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.
FILE_FLAG_RANDOM_ACCESS 0x10000000	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 topik ini.
FILE_FLAG_SESSION_AWARE 0x00800000	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.
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	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 topik ini.
FILE_FLAG_WRITE_THROUGH 0x80000000	Operasi tulis tidak akan melalui cache perantara apa pun, mereka akan langsung masuk ke disk. Untuk informasi tambahan, lihat bagian Perilaku Penembolokan topik ini.

dwSecurityQosFlags

Parameter dwSecurityQosFlags menentukan informasi SQOS. Untuk informasi selengkapnya, lihat tingkat peniruan .

Bendera keamanan	Arti
SECURITY_ANONYMOUS	Meniru klien di tingkat peniruan nama anonim.
SECURITY_CONTEXT_TRACKING	Mode pelacakan keamanan bersifat dinamis. Jika bendera ini tidak ditentukan, mode pelacakan keamanan bersifat statis.
SECURITY_DELEGATION	Meniru klien di tingkat peniruan delegasi.
SECURITY_EFFECTIVE_ONLY	Hanya aspek yang diaktifkan dari konteks keamanan klien yang tersedia untuk server. Jika Anda tidak menentukan bendera ini, semua aspek konteks keamanan klien tersedia. Ini memungkinkan klien untuk membatasi grup dan hak istimewa yang dapat digunakan server saat meniru klien.
SECURITY_IDENTIFICATION	Meniru klien di tingkat peniruan identifikasi.
SECURITY_IMPERSONATION	Meniru klien pada tingkat peniruan identitas. Ini adalah perilaku default jika tidak ada bendera lain yang ditentukan.

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 dapat 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.

lpSecurityDescriptor anggota 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 .

bInheritHandle anggota 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 dapat 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.

Komentar

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. Mereka 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 dihapus ke disk tanpa penundaan.

Jika FILE_FLAG_WRITE_THROUGH dan FILE_FLAG_NO_BUFFERING ditentukan, sehingga penembolokan sistem tidak berlaku, maka data segera dihapus ke disk tanpa melalui cache sistem Windows. Sistem operasi juga meminta write-through dari cache perangkat keras lokal hard disk ke media persisten.

Nota

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 File Buffering.

Permintaan write-through melalui FILE_FLAG_WRITE_THROUGH juga menyebabkan NTFS menghapus 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 FlushFileBuffers fungsi 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 disimpan 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 sepenuhnya dapat 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 rup 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 dwFileFlags anggota struktur CREATEFILE2_EXTENDED_PARAMETERS yang diteruskan dalam parameter pCreateExParams . Ada beberapa kompleksitas dan potensi jebakan saat menggunakan I/O asinkron; untuk informasi selengkapnya, lihatI/O Sinkron dan Asinkron .

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows 8 [aplikasi desktop \| Aplikasi UWP]
server minimum yang didukung	Windows Server 2012 [aplikasi desktop \| Aplikasi UWP]
Header	fileapi.h (termasuk Windows.h)

Lihat juga

CreateFile2

Struktur Manajemen File

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-01-23