Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
[Microsoft sangat merekomendasikan pengembang menggunakan sarana alternatif untuk mencapai kebutuhan aplikasi Anda. Banyak skenario yang dikembangkan TxF dapat dicapai melalui teknik yang lebih sederhana dan lebih tersedia. Selain itu, TxF mungkin tidak tersedia di versi Microsoft Windows yang akan datang. Untuk informasi lebih lanjut, dan alternatif TxF, silakan lihat Alternatif untuk menggunakanNTFS Transaksi.]
Membuat atau membuka file, aliran file, atau direktori sebagai operasi yang ditransaksikan. Fungsi mengembalikan handel yang dapat digunakan untuk mengakses objek.
Untuk melakukan operasi ini sebagai operasi yang tidak ditransaksikan atau mengakses objek selain file (misalnya, pipa bernama, perangkat fisik, mailslots), gunakan fungsi
Untuk informasi selengkapnya tentang transaksi, lihat bagian Keterangan dari topik ini.
Sintaksis
HANDLE CreateFileTransactedA(
[in] LPCSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
[in] DWORD dwCreationDisposition,
[in] DWORD dwFlagsAndAttributes,
[in, optional] HANDLE hTemplateFile,
[in] HANDLE hTransaction,
[in, optional] PUSHORT pusMiniVersion,
PVOID lpExtendedParameter
);
Parameter
[in] lpFileName
Nama objek yang akan dibuat atau dibuka.
Objek harus berada di komputer lokal; jika tidak, fungsi gagal dan kode kesalahan terakhir diatur ke ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.
Secara default, nama dibatasi untuk MAX_PATH karakter. Untuk memperpanjang batas ini menjadi 32.767 karakter lebar, tambahkan awal "\\?\" ke jalur. Untuk informasi selengkapnya, lihat Penamaan File, Jalur, dan Namespace.
Ujung
Dimulai dengan Windows 10, Versi 1607, Anda dapat memilih untuk menghapus batasan MAX_PATH tanpa prepending "\\?\". Lihat bagian "Batasan Panjang Jalur Maksimum" Penamaan File, Jalur, dan Namespace untuk detailnya.
Untuk membuat aliran file, tentukan nama file, titik dua, lalu nama aliran. Untuk informasi selengkapnya, lihat Aliran File.
[in] dwDesiredAccess
Akses ke objek, yang dapat diringkas sebagai baca, tulis, keduanya atau tidak sama sekali (nol). Nilai yang paling umum digunakan adalah GENERIC_READ, GENERIC_WRITE, atau keduanya (GENERIC_READ | GENERIC_WRITE). Untuk informasi selengkapnya, lihat Hak Akses Generik dan Keamanan File dan Hak Akses.
Jika parameter ini nol, aplikasi dapat mengkueri atribut file, direktori, atau perangkat tanpa mengakses file atau perangkat tersebut. Untuk informasi selengkapnya, lihat bagian Keterangan dari topik ini.
Anda tidak dapat meminta mode akses yang bertentangan dengan mode berbagi yang ditentukan dalam permintaan terbuka yang memiliki handel terbuka. Untuk informasi selengkapnya, lihat Membuat dan Membuka File.
[in] dwShareMode
Mode berbagi objek, yang dapat dibaca, ditulis, keduanya, hapus, semua ini, atau tidak ada (lihat tabel berikut).
Jika parameter ini nol dan CreateFileTransacted berhasil, objek tidak dapat dibagikan dan tidak dapat dibuka lagi hingga handel ditutup. Untuk informasi selengkapnya, lihat bagian Keterangan dari topik ini.
Anda tidak dapat meminta mode berbagi yang bertentangan dengan mode akses yang ditentukan dalam permintaan terbuka yang memiliki handel terbuka, karena itu akan mengakibatkan pelanggaran berbagi berikut: ERROR_SHARING_VIOLATION. Untuk informasi selengkapnya, lihat Membuat dan Membuka File.
Untuk mengaktifkan proses berbagi objek saat proses lain membuka objek, gunakan kombinasi satu atau beberapa nilai berikut untuk menentukan mode akses yang dapat mereka minta untuk membuka objek.
Catatan Opsi berbagi untuk setiap handel terbuka tetap berlaku hingga handel tersebut ditutup, terlepas dari konteks proses.
[in, optional] lpSecurityAttributes
Penunjuk ke struktur
Jika parameter
bInheritHandle anggota struktur menentukan apakah handel yang dikembalikan dapat diwariskan.
Jika anggota lpSecurityDescriptor NULL, objek yang terkait dengan handel yang dikembalikan diberi pendeskripsi keamanan default.
Untuk informasi selengkapnya, lihat bagian Keterangan dari topik ini.
[in] dwCreationDisposition
Tindakan yang harus diambil pada file yang ada dan tidak ada.
Untuk informasi selengkapnya, lihat bagian Keterangan dari topik ini.
Parameter ini harus menjadi salah satu nilai berikut, yang tidak dapat digabungkan.
[in] dwFlagsAndAttributes
Atribut dan bendera file, FILE_ATTRIBUTE_NORMAL menjadi nilai default yang paling umum.
Parameter ini dapat mencakup kombinasi atribut file yang tersedia (FILE_ATTRIBUTE_*). Semua atribut file lainnya mengambil alih FILE_ATTRIBUTE_NORMAL.
Parameter ini juga dapat berisi kombinasi bendera (FILE_FLAG_) untuk kontrol perilaku buffering, mode akses, dan bendera tujuan khusus lainnya. Ini dikombinasikan dengan nilai FILE_ATTRIBUTE_ apa pun.
Parameter ini juga dapat berisi informasi Kualitas Layanan Keamanan (SQOS) dengan menentukan bendera SECURITY_SQOS_PRESENT. Informasi bendera terkait SQOS tambahan disajikan dalam tabel dengan mengikuti atribut dan tabel bendera.
Catatan
Ketika CreateFileTransacted 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.
| Bendera | Arti |
|---|---|
|
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 Directory Handles. |
|
File akan dihapus segera setelah handel penulis terakhir yang ditransaksikan ke file ditutup, asalkan transaksi masih aktif. Jika file telah ditandai untuk penghapusan dan handel penulis yang ditransaksikan masih terbuka setelah transaksi selesai, file tidak akan dihapus.
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 sedang dibuka tanpa penembolokan sistem. Bendera ini tidak memengaruhi penembolokan hard disk atau file yang dipetakan memori. Ketika 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. Untuk menghapus metadata ke disk, gunakan fungsi Aplikasi harus memenuhi persyaratan tertentu saat bekerja dengan file yang dibuka dengan FILE_FLAG_NO_BUFFERING:
Aplikasi dapat menentukan ukuran sektor volume dengan memanggil fungsi |
|
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 |
|
File sedang dibuka atau dibuat untuk I/O asinkron. Ketika operasi selesai, peristiwa yang ditentukan dalam struktur Jika bendera ini ditentukan, file dapat digunakan untuk operasi baca dan tulis bersamaan. Sistem tidak mempertahankan penunjuk file, oleh karena itu Anda harus meneruskan posisi file ke fungsi baca dan tulis dalam struktur Jika bendera ini tidak ditentukan, maka operasi I/O diserialisasikan, bahkan jika panggilan ke fungsi baca dan tulis menentukan struktur TUMPANG TINDIH. |
|
File akan diakses 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 akan diakses secara acak. Sistem dapat menggunakan ini sebagai petunjuk untuk mengoptimalkan penembolokan file. |
|
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 ini akan diakses secara berurutan dari awal hingga akhir. Sistem dapat menggunakan ini sebagai petunjuk untuk mengoptimalkan penembolokan file. Jika aplikasi memindahkan penunjuk file untuk akses acak, penembolokan optimal mungkin tidak terjadi. Namun, operasi yang benar masih dijamin.
Menentukan bendera ini 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. Bendera ini tidak berpengaruh jika sistem file tidak mendukung I/O cache dan FILE_FLAG_NO_BUFFERING. |
|
Operasi tulis tidak akan melalui cache perantara apa pun, mereka akan langsung masuk ke disk.
Jika 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_NO_BUFFERING juga ditentukan, sehingga penembolokan sistem tidak berlaku, maka data segera dihapus ke disk tanpa melalui cache sistem. Sistem operasi juga meminta penulisan melalui cache hard disk ke media persisten. Namun, tidak semua perangkat keras mendukung kemampuan write-through ini. |
Parameter
[in, optional] 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, CreateFileTransacted mengabaikan file templat.
Saat membuka file terenkripsi EFS baru, file mewarisi DACL dari direktori induknya.
[in] hTransaction
Handel ke transaksi. Handel ini dikembalikan oleh fungsi
[in, optional] pusMiniVersion
Miniversi yang akan dibuka. Jika transaksi yang ditentukan dalam hTransaction bukan transaksi yang memodifikasi file, parameter ini harus NULL. Jika tidak, parameter ini dapat menjadi pengidentifikasi miniversi yang dikembalikan oleh kode kontrol FSCTL_TXFS_CREATE_MINIVERSION, atau salah satu nilai berikut.
lpExtendedParameter
Parameter ini dicadangkan dan harus NULL.
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
Saat menggunakan handel yang dikembalikan oleh CreateFileTransacted, gunakan versi fungsi I/O file yang ditransaksikan alih-alih fungsi I/O file standar jika sesuai. Untuk informasi selengkapnya, lihat Pertimbangan Pemrograman untukNTFS Transaksi.
Saat membuka handel yang ditransaksikan ke direktori, handel tersebut harus memiliki izin FILE_WRITE_DATA (FILE_ADD_FILE) dan FILE_APPEND_DATA (FILE_ADD_SUBDIRECTORY). Ini termasuk dalam izin FILE_GENERIC_WRITE. Anda harus membuka direktori dengan lebih sedikit izin jika Anda hanya menggunakan handel untuk membuat file atau subdirektori; jika tidak, pelanggaran berbagi dapat terjadi.
Anda tidak dapat membuka file dengan tingkat akses FILE_EXECUTE ketika file tersebut adalah bagian dari transaksi lain (yaitu, aplikasi lain membukanya dengan memanggil CreateFileTransacted). Ini berarti bahwa
Ketika aplikasi yang tidak ditransaksikan memanggil CreateFileTransacted dengan MAXIMUM_ALLOWED ditentukan untuk lpSecurityAttributes, handel dibuka dengan tingkat akses yang sama setiap saat. Ketika aplikasi yang ditransaksikan memanggil CreateFileTransacted dengan MAXIMUM_ALLOWED ditentukan untuk lpSecurityAttributes, handel dibuka dengan jumlah akses yang berbeda berdasarkan apakah file dikunci oleh transaksi. Misalnya, jika aplikasi panggilan memiliki tingkat akses FILE_EXECUTE untuk file, aplikasi hanya mendapatkan akses ini jika file yang sedang dibuka tidak dikunci oleh transaksi, atau dikunci oleh transaksi dan aplikasi sudah menjadi pembaca yang ditransaksikan untuk file tersebut.
Lihat
Gunakan fungsi
Beberapa sistem file, seperti sistem file NTFS, mendukung kompresi atau enkripsi untuk file dan direktori individual. Pada volume yang diformat untuk sistem file semacam itu, file baru mewarisi atribut kompresi dan enkripsi direktorinya.
Anda tidak dapat menggunakan CreateFileTransacted untuk mengontrol kompresi pada file atau direktori. Untuk informasi selengkapnya, lihatKompresi dan Dekompresi File
Perilaku tautan simbolis—Jika panggilan ke fungsi ini membuat file baru, tidak ada perubahan perilaku.
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 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.
Seperti yang dinyatakan sebelumnya, jika parameter lpSecurityAttributesNULL, handel yang dikembalikan oleh CreateFileTransacted tidak dapat diwariskan oleh proses anak apa pun yang mungkin dibuat aplikasi Anda. Informasi berikut mengenai parameter ini juga berlaku:
- Jika 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 agar memiliki efek pada file dan direktori tersebut, yang dapat ditentukan dengan menggunakan GetVolumeInformation
| Teknologi | Didukung |
|---|---|
| Protokol Server Message Block (SMB) 3.0 | Tidak |
| Failover Transparan (TFO) SMB 3.0 | Tidak |
| SMB 3.0 dengan Scale-out File Shares (SO) | Tidak |
| Sistem File Volume Bersama Kluster (CsvFS) | Tidak |
| Sistem File Tangguh (ReFS) | Tidak |
Perhatikan bahwa SMB 3.0 tidak mendukung TxF.
File
Jika Anda mencoba membuat file pada drive floppy yang tidak memiliki disket atau drive CD-ROM yang tidak memiliki CD, sistem akan menampilkan pesan bagi pengguna untuk memasukkan disk atau CD. Untuk mencegah sistem menampilkan pesan ini, panggil fungsiUntuk informasi selengkapnya, lihat Membuat dan Membuka 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 GENERIC_READ | GENERIC_WRITE daripada menggunakan GENERIC_WRITE saja. Kode yang dihasilkan lebih cepat, karena pengalih dapat menggunakan manajer cache dan mengirim lebih sedikit SMB dengan lebih banyak data. Kombinasi ini juga menghindari masalah di mana menulis ke file di seluruh jaringan kadang-kadang dapat mengembalikan ERROR_ACCESS_DENIED.
Aliran File
Pada sistem file NTFS, Anda dapat menggunakan CreateFileTransacted untuk membuat aliran terpisah dalam file.Untuk informasi selengkapnya, lihat Aliran File.
Direktori
Aplikasi tidak dapat membuat direktori dengan menggunakan CreateFileTransacted, oleh karena itu hanya nilai OPEN_EXISTING yang valid untuk dwCreationDisposition untuk kasus penggunaan ini. Untuk membuat direktori, aplikasi harus memanggil CreateDirectoryTransacted, CreateDirectory atau CreateDirectoryEx.Untuk membuka direktori menggunakan CreateFileTransacted, tentukan bendera FILE_FLAG_BACKUP_SEMANTICS sebagai bagian dari dwFlagsAndAttributes. Pemeriksaan keamanan yang sesuai masih berlaku ketika bendera ini digunakan tanpa hak istimewa SE_BACKUP_NAME dan SE_RESTORE_NAME.
Saat menggunakan CreateFileTransacted 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.
Nota
Header winbase.h mendefinisikan CreateFileTransacted sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
| Syarat | Nilai |
|---|---|
| klien minimum yang didukung | Windows Vista [hanya aplikasi desktop] |
| server minimum yang didukung |
Windows Server 2008 [hanya aplikasi desktop] |
| Platform Target |
Windows |
| Header |
winbase.h (termasuk Windows.h) |
| Pustaka |
Kernel32.lib |
| DLL |
Kernel32.dll |
Lihat juga
Enkripsi File
Keamanan File dan Hak Akses
Aliran File
Topik Ringkasan
Pertimbangan Pemrograman untuk Transaksi NTFS
ReadFile
WriteFile