Fungsi CreateFile2 (fileapi.h)
Membuat atau membuka file atau perangkat I/O. Perangkat I/O yang paling umum digunakan adalah sebagai berikut: file, aliran file, direktori, disk fisik, volume, buffer konsol, tape drive, sumber daya komunikasi, mailslot, dan pipa. Fungsi mengembalikan handel yang dapat digunakan untuk mengakses file atau perangkat untuk berbagai jenis I/O tergantung pada file atau perangkat dan bendera dan atribut yang ditentukan.
Saat dipanggil dari aplikasi Windows Store, CreateFile2 disederhanakan. Anda hanya dapat membuka file atau direktori di dalam direktori ApplicationData.LocalFolder atau Package.InstalledLocation. Anda tidak dapat membuka pipa atau mailslots bernama atau membuat file terenkripsi (FILE_ATTRIBUTE_ENCRYPTED).
Sintaksis
HANDLE CreateFile2(
[in] LPCWSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in] DWORD dwCreationDisposition,
[in, optional] LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
);
Parameter
[in] lpFileName
Nama file atau perangkat yang akan dibuat atau dibuka.
Untuk informasi tentang nama perangkat khusus, lihat Menentukan Nama Perangkat MS-DOS.
Untuk membuat aliran file, tentukan nama file, titik dua, lalu nama aliran. Untuk informasi selengkapnya, lihat Aliran File.
[in] dwDesiredAccess
Akses yang diminta ke file atau perangkat, yang dapat diringkas sebagai baca, tulis, keduanya atau bukan nol).
Nilai yang paling umum digunakan adalah GENERIC_READ, GENERIC_WRITE, atau keduanya (GENERIC_READ | GENERIC_WRITE
). Untuk informasi selengkapnya, lihat Hak Akses Generik, Keamanan File dan Hak Akses, Konstanta Hak Akses File, dan ACCESS_MASK.
Jika parameter ini nol, aplikasi dapat meminta metadata tertentu seperti atribut file, direktori, atau perangkat tanpa mengakses file atau perangkat tersebut, bahkan jika akses GENERIC_READ akan ditolak.
Anda tidak dapat meminta mode akses yang bertentangan dengan mode berbagi yang ditentukan oleh parameter dwShareMode dalam permintaan terbuka yang sudah memiliki handel terbuka.
Untuk informasi selengkapnya, lihat bagian Keterangan topik ini dan Membuat dan Membuka File.
[in] dwShareMode
Mode berbagi file atau perangkat yang diminta, yang dapat dibaca, ditulis, keduanya, hapus, semua ini, atau tidak ada (lihat tabel berikut). Permintaan akses ke atribut atau atribut yang diperluas tidak terpengaruh oleh bendera ini.
Jika parameter ini nol dan CreateFile2 berhasil, file atau perangkat tidak dapat dibagikan dan tidak dapat dibuka lagi sampai handel ke file atau perangkat ditutup. Untuk informasi selengkapnya, lihat bagian Keterangan.
Anda tidak dapat meminta mode berbagi yang bertentangan dengan mode akses yang ditentukan dalam permintaan yang ada yang memiliki handel terbuka. CreateFile2 akan gagal dan fungsi GetLastError akan mengembalikan ERROR_SHARING_VIOLATION.
Untuk mengaktifkan proses berbagi file atau perangkat saat proses lain membuka file atau perangkat, gunakan kombinasi yang kompatibel dari satu atau beberapa nilai berikut. Untuk informasi selengkapnya tentang kombinasi parameter ini yang valid dengan parameter
[in] dwCreationDisposition
Tindakan yang harus diambil pada file atau perangkat yang ada atau tidak ada.
Untuk perangkat selain file, parameter ini biasanya diatur ke OPEN_EXISTING.
Untuk informasi selengkapnya, lihat bagian Keterangan.
Parameter ini harus merupakan salah satu nilai berikut, yang tidak dapat digabungkan:
[in, optional] pCreateExParams
Penunjuk ke struktur CREATEFILE2_EXTENDED_PARAMETERS opsional.
Mengembalikan nilai
Jika fungsi berhasil, nilai pengembalian adalah handel terbuka ke file, perangkat, pipa bernama, atau slot email yang ditentukan.
Jika fungsi gagal, nilai yang dikembalikan adalah INVALID_HANDLE_VALUE. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.
Komentar
Untuk mengkompilasi aplikasi yang menggunakan fungsi
CreateFile2 mendukung interaksi file dan sebagian besar jenis perangkat dan mekanisme I/O lainnya yang tersedia untuk pengembang Windows. Bagian ini mencoba untuk mencakup berbagai masalah yang mungkin dialami pengembang saat menggunakan CreateFile2 dalam konteks yang berbeda dan dengan jenis I/O yang berbeda. Teks mencoba menggunakan kata file hanya ketika merujuk khusus ke data yang disimpan dalam file aktual pada sistem file. Namun, beberapa penggunaan file mungkin merujuk lebih umum ke objek I/O yang mendukung mekanisme seperti file. Penggunaan liberal istilah ini file sangat lazim dalam nama konstanta dan nama parameter karena alasan historis yang disebutkan sebelumnya.
Ketika aplikasi selesai menggunakan handel objek yang dikembalikan oleh
Beberapa sistem file, seperti sistem file NTFS, mendukung kompresi atau enkripsi untuk file dan direktori individual. Pada volume yang memiliki sistem file yang dipasang dengan dukungan ini, file baru mewarisi atribut kompresi dan enkripsi direktorinya.
Anda tidak dapat menggunakan
Jika
- Jika variabel anggota bInheritHandle tidak FALSE, yang merupakan nilai bukan nol, maka handel dapat diwariskan. Oleh karena itu sangat penting anggota struktur ini diinisialisasi dengan benar untuk FALSE jika Anda tidak berniat menangani untuk diwariskan.
- Daftar kontrol akses (ACL) dalam deskriptor keamanan default untuk file atau direktori diwarisi dari direktori induknya.
- Sistem file target harus mendukung keamanan pada file dan direktori untuk lpSecurityDescriptor anggota untuk memiliki efek pada mereka, yang dapat ditentukan dengan menggunakan GetVolumeInformation.
Teknologi | Didukung |
---|---|
Protokol Server Message Block (SMB) 3.0 | Ya |
Failover Transparan (TFO) SMB 3.0 | Tidak |
SMB 3.0 dengan Scale-out File Shares (SO) | Tidak |
Sistem File Volume Bersama Kluster (CsvFS) | Ya |
Sistem File Tangguh (ReFS) | Ya |
Perilaku Tautan Simbolis
Jika panggilan ke fungsi ini membuat file, tidak ada perubahan perilaku. Selain itu, pertimbangkan informasi berikut mengenai bendera-
Jika FILE_FLAG_OPEN_REPARSE_POINT ditentukan:
- Jika file yang ada dibuka dan merupakan tautan simbolis, handel yang dikembalikan adalah handel ke tautan simbolis.
- Jika TRUNCATE_EXISTING atau FILE_FLAG_DELETE_ON_CLOSE ditentukan, file yang terpengaruh adalah tautan simbolis.
-
Jika FILE_FLAG_OPEN_REPARSE_POINT tidak ditentukan:
- Jika file yang ada dibuka dan merupakan tautan simbolis, handel yang dikembalikan adalah handel ke target.
- Jika CREATE_ALWAYS, TRUNCATE_EXISTING, atau FILE_FLAG_DELETE_ON_CLOSE ditentukan, file yang terpengaruh adalah target.
File
Jika Anda mengganti nama atau menghapus file lalu memulihkannya segera setelahnya, sistem mencari cache untuk informasi file yang akan dipulihkan. Informasi cache mencakup pasangan nama pendek/panjang dan waktu pembuatannya.Jika Anda memanggil
Parameter
Ketika aplikasi membuat file di seluruh jaringan, lebih baik menggunakan
Untuk informasi selengkapnya, lihat Membuat dan Membuka File.
Aliran File
Pada sistem file NTFS, Anda dapat menggunakanDirektori
Aplikasi tidak dapat membuat direktori dengan menggunakan CreateFile2, oleh karena itu hanya nilai OPEN_EXISTING yang valid untuk dwCreationDisposition untuk kasus penggunaan ini. Untuk membuat direktori, aplikasi harus memanggil CreateDirectory atau CreateDirectoryEx.Untuk membuka direktori menggunakan
Saat menggunakan CreateFile2 untuk membuka direktori selama defragmentasi volume sistem file FAT atau FAT32, jangan tentukan hak akses MAXIMUM_ALLOWED. Akses ke direktori ditolak jika ini dilakukan. Tentukan akses GENERIC_READ tepat sebagai gantinya.
Untuk informasi selengkapnya, lihat Tentang Manajemen Direktori.
Disk fisik dan Volume
Akses langsung ke disk atau ke volume dibatasi.Anda dapat menggunakan fungsi
Persyaratan berikut harus dipenuhi agar panggilan tersebut berhasil:
- Pemanggil harus memiliki hak administratif. Untuk informasi selengkapnya, lihat Berjalan dengan Hak Istimewa Khusus.
- Parameter
dwCreationDisposition harus memiliki bendera OPEN_EXISTING . - Saat membuka volume atau disket, parameter
dwShareMode harus memiliki bendera FILE_SHARE_WRITE .
Tali | Arti |
---|---|
"\\.\PhysicalDrive0" | Membuka drive fisik pertama. |
"\\.\PhysicalDrive2" | Membuka drive fisik ketiga. |
Untuk mendapatkan pengidentifikasi drive fisik untuk volume, buka handel ke volume dan panggil fungsi DeviceIoControl dengan IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS. Kode kontrol ini mengembalikan nomor disk dan offset untuk masing-masing volume satu atau beberapa tingkat; volume dapat mencakup beberapa disk fisik.
Untuk contoh membuka drive fisik, lihat Memanggil DeviceIoControl.
Saat membuka volume atau drive media yang dapat dilepas (misalnya, disk drive floppy atau flash memory thumb drive), string lpFileName
Tali | Arti |
---|---|
"\\.\A:" | Membuka disk disket drive A. |
"\\.\C:" | Membuka volume C: . |
"\\.\C:\" | Membuka sistem file volume C: . |
Anda juga dapat membuka volume dengan merujuk ke nama volumenya. Untuk informasi selengkapnya, lihat Penamaan Volume.
Volume berisi satu atau beberapa sistem file yang dipasang. Handel volume dapat dibuka sebagai non-cached atas kebijakan sistem file tertentu, bahkan ketika opsi yang tidak di-cache tidak ditentukan dalam CreateFile2. Anda harus berasumsi bahwa semua sistem file Microsoft membuka handel volume sebagai non-cache. Pembatasan I/O yang tidak di-cache untuk file juga berlaku untuk volume.
Sistem file mungkin atau mungkin tidak memerlukan perataan buffer meskipun data tidak di-cache. Namun, jika opsi non-cache ditentukan saat membuka volume, perataan buffer diberlakukan terlepas dari sistem file pada volume. Disarankan pada semua sistem file yang Anda buka handel volumenya sebagai non-cache, dan ikuti pembatasan I/O yang tidak di-cache.
Perangkat Pengubah
Kode kontrol IOCTL_CHANGER_* untuk DeviceIoControl menerima handel ke perangkat pengubah. Untuk membuka perangkat pengubah, gunakan nama file formulir berikut: "\\.\Changerx" di mana x adalah angka yang menunjukkan perangkat mana yang akan dibuka, dimulai dengan nol. Untuk membuka perangkat pengubah nol dalam aplikasi yang ditulis dalam C atau C++, gunakan nama file berikut: "\\\\.\Changer0".Tape Drive
Anda dapat membuka drive pita dengan menggunakan nama file formulir berikut: "\\.\TAPEx" di mana x adalah angka yang menunjukkan drive mana yang akan dibuka, dimulai dengan nol drive pita. Untuk membuka tape drive nol dalam aplikasi yang ditulis dalam C atau C++, gunakan nama file berikut: "\\\\.\TAPE0".Untuk informasi selengkapnya, lihat Backup.
Sumber Daya Komunikasi
FungsiUntuk menentukan nomor port COM yang lebih besar dari 9, gunakan sintaks berikut: "\.\COM10". Sintaks ini berfungsi untuk semua nomor port dan perangkat keras yang memungkinkan nomor port COM ditentukan.
Untuk informasi selengkapnya tentang komunikasi, lihat Communications.
Konsol
FungsiParameter | Nilai |
---|---|
lpFileName |
Gunakan nilai CONIN$ untuk menentukan input konsol.
Gunakan nilai CONOUT$ untuk menentukan output konsol. CONIN$ mendapatkan handel ke buffer input konsol, bahkan jika fungsi setStdHandle CONOUT$ mendapatkan handel ke buffer layar aktif, bahkan jika SetStdHandle mengalihkan handel output standar. Untuk mendapatkan handel output standar, gunakan GetStdHandle. |
dwDesiredAccess |
GENERIC_READ | GENERIC_WRITE lebih disukai, tetapi salah satu dapat membatasi akses.
|
dwShareMode |
Saat membuka CONIN$, tentukan FILE_SHARE_READ. Saat membuka CONOUT$, tentukan FILE_SHARE_WRITE.
Jika proses panggilan mewarisi konsol, atau jika proses anak harus dapat mengakses konsol, parameter ini harus |
dwCreationDisposition |
Anda harus menentukan |
Atur anggota struktur
Anggota | Nilai |
---|---|
lpSecurityAttributes | Jika Anda ingin konsol diwariskan, bInheritHandle anggota struktur SECURITY_ATTRIBUTES harus TRUE. |
dwFileAttributes
dwFileFlags dwSecurityQosFlags hTemplateFile |
Diabaikan. |
Tabel berikut ini memperlihatkan berbagai pengaturan dwDesiredAccess dan lpFileName.
lpFileName | dwDesiredAccess | Hasil |
---|---|---|
"CON" | GENERIC_READ | Membuka konsol untuk input. |
"CON" | GENERIC_WRITE | Membuka konsol untuk output. |
"CON" | GENERIC_READ | GENERIC_WRITE |
Menyebabkan |
Mailslots
JikaUntuk informasi selengkapnya, lihat Mailslots .
Pipa
Jika CreateFile2 membuka akhir klien dari pipa bernama, fungsi menggunakan instans pipa bernama apa pun yang berada dalam status mendengarkan. Proses pembukaan dapat menduplikasi handel sebanyak yang diperlukan, tetapi setelah dibuka, instans pipa bernama tidak dapat dibuka oleh klien lain. Akses yang ditentukan ketika pipa dibuka harus kompatibel dengan akses yang ditentukan dalam parameter dwOpenMode fungsi CreateNamedPipe.Jika fungsi
Jika ada setidaknya satu instans pipa aktif tetapi tidak ada pipa pendengar yang tersedia di server, yang berarti semua instans pipa saat ini terhubung, CreateFile2 gagal dengan ERROR_PIPE_BUSY.
Untuk informasi selengkapnya, lihat Pipes.
Persyaratan
Syarat | Nilai |
---|---|
klien minimum yang didukung | Windows 8 [aplikasi desktop | Aplikasi UWP] |
server minimum yang didukung |
Windows Server 2012 [aplikasi desktop | Aplikasi UWP] |
Platform Target |
Windows |
Header |
fileapi.h (termasuk Windows.h) |
Pustaka |
Kernel32.lib |
DLL |
Kernel32.dll |
Lihat juga
Tentang Manajemen Direktori
Tentang Manajemen Volume
Pencadangan
Komunikasi
Membuat, Menghapus, dan Memelihara File
Kontrol Input dan Output Perangkat (IOCTL)
DeviceIoControl
Enkripsi File
Keamanan File dan Hak Akses
Aliran File
GetLastError
Port Penyelesaian I/O
Konsep I/O
Mendapatkan dan Mengatur Informasi File
Topik Ringkasan
Pipa
ReadFile
ReadFileEx
Berjalan dengan Hak Istimewa khusus
SetFileAttributes
WriteFile