Fungsi CreateFileTransactedA (winbase.h)

[Microsoft sangat menyarankan pengembang menggunakan cara 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 menggunakan Transactional NTFS.]

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 untuk mengakses objek selain file (misalnya, pipa bernama, perangkat fisik, mailslots), gunakan fungsi CreateFile .

Untuk informasi selengkapnya tentang transaksi, lihat bagian Keterangan dari topik ini.

Sintaks

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 terbatas pada MAX_PATH karakter. Untuk memperpanjang batas ini menjadi 32.767 karakter lebar, tambahkan "\\?\" ke jalur. Untuk informasi selengkapnya, lihat Menamai File, Jalur, dan Namespace.

Tip

Dimulai dengan Windows 10, Versi 1607, Anda dapat ikut serta untuk menghapus batasan MAX_PATH tanpa menambahkan awalan "\\?\". Lihat bagian "Batasan Panjang Jalur Maksimum" dari 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 keduanya (nol). Nilai yang paling umum digunakan adalah GENERIC_READ, GENERIC_WRITE, atau keduanya (GENERIC_WRITE GENERIC_READ | ). 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 berkonflik 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, baik, 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 sampai handel ditutup. Untuk informasi selengkapnya, lihat bagian Keterangan dari topik ini.

Anda tidak dapat meminta mode berbagi yang berkonflik 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.
 
Nilai Makna
0
0x00000000
Menonaktifkan operasi terbuka berikutnya pada objek untuk meminta semua jenis akses ke objek tersebut.
FILE_SHARE_DELETE
0x00000004
Memungkinkan operasi terbuka berikutnya pada objek untuk meminta akses penghapusan.

Jika tidak, proses lain tidak dapat membuka objek jika meminta akses penghapusan.

Jika bendera ini tidak ditentukan, tetapi objek telah dibuka untuk akses penghapusan, fungsi gagal.

FILE_SHARE_READ
0x00000001
Memungkinkan operasi terbuka berikutnya pada objek untuk meminta akses baca.

Jika tidak, proses lain tidak dapat membuka objek jika meminta akses baca.

Jika bendera ini tidak ditentukan, tetapi objek telah dibuka untuk akses baca, fungsi gagal.

FILE_SHARE_WRITE
0x00000002
Memungkinkan operasi terbuka berikutnya pada objek untuk meminta akses tulis.

Jika tidak, proses lain tidak dapat membuka objek jika meminta akses tulis.

Jika bendera ini tidak ditentukan, tetapi objek telah dibuka untuk akses tulis atau memiliki pemetaan file dengan akses tulis, fungsi gagal.

[in, optional] lpSecurityAttributes

Penunjuk ke struktur SECURITY_ATTRIBUTES yang berisi deskriptor keamanan opsional dan juga menentukan apakah handel yang dikembalikan dapat diwariskan oleh proses turunan atau tidak. Parameternya bisa NULL.

Jika parameter lpSecurityAttributes adalah NULL, handel yang dikembalikan oleh CreateFileTransacted tidak dapat diwarisi oleh proses anak apa pun yang dapat dibuat aplikasi Anda dan objek yang terkait dengan handel yang dikembalikan mendapatkan pendeskripsi keamanan default.

Anggota bInheritHandle dari struktur menentukan apakah handel yang dikembalikan dapat diwariskan.

Anggota lpSecurityDescriptor dari struktur menentukan deskriptor keamanan untuk objek, tetapi mungkin juga NULL.

Jika anggota lpSecurityDescriptor adalah NULL, objek yang terkait dengan handel yang dikembalikan diberi pendeskripsi keamanan default.

CreateFileTransacted mengabaikan anggota lpSecurityDescriptor saat membuka file yang ada, tetapi terus menggunakan anggota bInheritHandle .

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 merupakan salah satu nilai berikut, yang tidak dapat digabungkan.

Nilai Makna
CREATE_ALWAYS
2
Membuat file baru, selalu.

Jika file yang ditentukan ada dan dapat ditulis, fungsi memotong file, fungsi berhasil, dan kode kesalahan terakhir diatur ke ERROR_ALREADY_EXISTS (183).

Jika file yang ditentukan tidak ada dan merupakan jalur yang valid, file baru dibuat, fungsi berhasil, dan kode kesalahan terakhir diatur ke nol.

Untuk informasi selengkapnya, lihat bagian Keterangan dari topik ini.

CREATE_NEW
1
Membuat file baru, hanya jika belum ada.

Jika file yang ditentukan ada, fungsi gagal dan kode kesalahan terakhir diatur ke ERROR_FILE_EXISTS (80).

Jika file yang ditentukan tidak ada dan merupakan jalur yang valid ke lokasi bisa-tulis, file baru akan dibuat.

OPEN_ALWAYS
4
Selalu membuka file.

Jika file yang ditentukan ada, fungsi berhasil dan kode kesalahan terakhir diatur ke ERROR_ALREADY_EXISTS (183).

Jika file yang ditentukan tidak ada dan merupakan jalur yang valid ke lokasi bisa-tulis, fungsi membuat file dan kode kesalahan terakhir diatur ke nol.

OPEN_EXISTING
3
Membuka file atau perangkat, hanya jika ada.

Jika file yang ditentukan tidak ada, fungsi gagal dan kode kesalahan terakhir diatur ke ERROR_FILE_NOT_FOUND (2).

Untuk informasi selengkapnya, lihat bagian Keterangan dari topik ini.

TRUNCATE_EXISTING
5
Membuka file dan memotongnya sehingga ukurannya nol byte, hanya jika ada.

Jika file yang ditentukan tidak ada, fungsi gagal dan kode kesalahan terakhir diatur ke ERROR_FILE_NOT_FOUND (2).

Proses panggilan harus membuka file dengan GENERIC_WRITE bit yang ditetapkan sebagai bagian dari parameter dwDesiredAccess .

[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 Keamanan Layanan (SQOS) dengan menentukan bendera SECURITY_SQOS_PRESENT . Informasi bendera terkait SQOS tambahan disajikan dalam tabel mengikuti atribut dan tabel bendera.

Catatan  

Ketika CreateFileTransacted membuka file yang ada, file 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.

 
Atribut dan bendera file berikut hanya digunakan untuk objek file, bukan jenis objek lain yang terbuka CreateFileTransacted (informasi tambahan dapat ditemukan di bagian Keterangan topik ini). Untuk akses tingkat lanjut ke atribut file lainnya, lihat SetFileAttributes. Untuk daftar lengkap semua atribut file dengan nilai dan deskripsinya, lihat Konstanta Atribut File.
Atribut Makna
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, lihat Enkripsi File.

Bendera ini tidak berpengaruh jika FILE_ATTRIBUTE_SYSTEM juga ditentukan.

FILE_ATTRIBUTE_HIDDEN
2 (0x2)
File disembunyikan. Jangan sertakan dalam daftar direktori biasa.
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 Penyimpanan Jarak Jauh, perangkat lunak manajemen penyimpanan hierarkis. Aplikasi tidak boleh secara segan-segan mengubah atribut ini.
FILE_ATTRIBUTE_READONLY
1 (0x1)
File bersifat baca-saja. Aplikasi dapat membaca file, tetapi tidak dapat menulis 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. 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. Jika tidak, data ditulis setelah handel ditutup.
 
Bendera Makna
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 Handel Direktori.

FILE_FLAG_DELETE_ON_CLOSE
0x04000000
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 tersebut akan gagal, kecuali mode berbagi FILE_SHARE_DELETE ditentukan.

FILE_FLAG_NO_BUFFERING
0x20000000
File sedang dibuka tanpa penembolokan sistem. Bendera ini tidak mempengaruhi 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 ditahan di cache. Selain itu, metadata file mungkin masih di-cache. Untuk menghapus metadata ke disk, gunakan fungsi FlushFileBuffers .

Aplikasi harus memenuhi persyaratan tertentu saat bekerja dengan file yang dibuka dengan FILE_FLAG_NO_BUFFERING:

  • Akses file harus dimulai pada offset byte dalam file yang merupakan kelipatan bilangan bulat dari ukuran sektor volume.
  • Akses file harus untuk jumlah byte yang merupakan kelipatan bilangan bulat dari ukuran sektor volume. Misalnya, jika ukuran sektor adalah 512 byte, aplikasi dapat meminta baca dan tulis 512, 1024, 1536, atau 2048 byte, tetapi tidak 335, 981, atau 7171 byte.
  • Alamat buffer untuk operasi baca dan tulis harus diselaraskan dengan sektor, yang berarti diselaraskan pada alamat dalam memori yang merupakan kelipatan bilangan bulat dari ukuran sektor volume. Tergantung pada disk, persyaratan ini mungkin tidak diberlakukan.
Salah satu cara untuk menyelaraskan buffer pada kelipatan bilangan bulat dari ukuran sektor volume adalah dengan menggunakan VirtualAlloc untuk mengalokasikan buffer. Ini mengalokasikan memori yang selaras pada alamat yang merupakan kelipatan bilangan bulat dari ukuran halaman memori sistem operasi. Karena ukuran halaman memori dan sektor volume adalah kekuatan 2, memori ini juga diselaraskan pada alamat yang merupakan kelipatan bilangan bulat dari ukuran sektor volume. Halaman memori berukuran 4 atau 8 KB; sektor adalah 512 byte (hard disk), 2048 byte (CD), atau 4096 byte (hard disk), dan oleh karena itu, sektor volume tidak pernah bisa lebih besar dari halaman memori.

Aplikasi dapat menentukan ukuran sektor volume dengan memanggil fungsi GetDiskFreeSpace .

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 pemilah ulang normal tidak akan terjadi; CreateFileTransacted akan mencoba membuka titik reparse. Ketika file dibuka, handel file dikembalikan, apakah filter yang mengontrol titik pemilah ulang beroperasi atau tidak. Bendera ini tidak dapat digunakan dengan bendera CREATE_ALWAYS . Jika file bukan titik pemilah ulang, maka bendera ini diabaikan.
FILE_FLAG_OVERLAPPED
0x40000000
File sedang dibuka atau dibuat untuk I/O asinkron. Ketika operasi selesai, peristiwa yang ditentukan dalam struktur TUMPANG TINDIH diatur ke status sinyal. Operasi yang membutuhkan banyak waktu untuk memproses pengembalian ERROR_IO_PENDING.

Jika bendera ini ditentukan, file dapat digunakan untuk operasi baca dan tulis secara bersamaan. Sistem tidak mempertahankan penunjuk file, oleh karena itu Anda harus meneruskan posisi file ke fungsi baca dan tulis dalam struktur yang TUMPANG TINDIH atau memperbarui penunjuk file.

Jika bendera ini tidak ditentukan, maka operasi I/O diserialisasikan, bahkan jika panggilan ke fungsi baca dan tulis menentukan struktur yang TUMPANG TINDIH .

FILE_FLAG_POSIX_SEMANTICS
0x01000000
File akan diakses sesuai dengan aturan POSIX. Ini termasuk mengizinkan beberapa file dengan nama, hanya berbeda jika, untuk sistem file yang mendukung penamaan tersebut. Berhati-hatilah 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
File akan diakses secara acak. Sistem dapat menggunakan ini sebagai petunjuk untuk mengoptimalkan penembolokan file.
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
File 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.

FILE_FLAG_WRITE_THROUGH
0x80000000
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 dibersihkan ke disk tanpa penundaan.

Jika FILE_FLAG_NO_BUFFERING juga ditentukan, sehingga penembolokan sistem tidak berlaku, maka data segera dibersihkan 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 dwFlagsAndAttributes juga dapat menentukan informasi Kualitas Keamanan Layanan. Untuk informasi selengkapnya, lihat Tingkat Peniruan. Ketika aplikasi panggilan menentukan bendera SECURITY_SQOS_PRESENT sebagai bagian dari dwFlagsAndAttributes, aplikasi tersebut juga dapat berisi satu atau beberapa nilai berikut.

Bendera keamanan Makna
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 identitas.
SECURITY_IMPERSONATION
Meniru klien di tingkat peniruan. Ini adalah perilaku default jika tidak ada bendera lain yang ditentukan bersama dengan bendera SECURITY_SQOS_PRESENT .

[in, optional] hTemplateFile

Handel yang valid ke file templat dengan akses GENERIC_READ kanan. File templat menyediakan atribut file dan atribut yang diperluas untuk file yang sedang dibuat. Parameter ini bisa 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 CreateTransaction .

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

Nilai Makna
TXFS_MINIVERSION_COMMITTED_VIEW
0x0000
Tampilan file pada penerapan terakhirnya.
TXFS_MINIVERSION_DIRTY_VIEW
0xFFFF
Tampilan file saat sedang dimodifikasi oleh transaksi.
TXFS_MINIVERSION_DEFAULT_VIEW
0xFFFE
Tampilan file yang diterapkan atau kotor, tergantung pada konteksnya. Transaksi yang memodifikasi file mendapatkan tampilan kotor, sementara transaksi yang tidak memodifikasi file mendapatkan tampilan yang diterapkan.

lpExtendedParameter

Parameter ini dicadangkan dan harus NULL.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah handel terbuka ke file, perangkat, pipa bernama, atau slot email yang ditentukan.

Jika fungsi gagal, nilai yang dikembalikan INVALID_HANDLE_VALUE. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

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 untuk Transactional NTFS.

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 CreateFileTransacted gagal jika tingkat akses FILE_EXECUTE atau FILE_ALL_ACCESS ditentukan

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 Transactional NTFS untuk deskripsi lengkap tentang operasi yang ditransaksikan.

Gunakan fungsi CloseHandle untuk menutup handel objek yang dikembalikan oleh CreateFileTransacted saat handel tidak lagi diperlukan, dan sebelum melakukan atau mengembalikan transaksi.

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 pemadatan pada file atau direktori. Untuk informasi selengkapnya, lihat Kompresi dan Dekompresi File, dan Enkripsi 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_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.
Penulisan multi-sektor tidak dijamin sebagai atomik kecuali Anda menggunakan transaksi (artinya, handel yang dibuat adalah handel yang ditransaksikan). Penulisan sektor tunggal bersifat atomik. Penulisan multi-sektor yang di-cache mungkin tidak selalu ditulis ke disk; oleh karena itu, tentukan FILE_FLAG_WRITE_THROUGH untuk memastikan bahwa seluruh penulisan multi-sektor ditulis ke disk tanpa penembolokan.

Seperti yang dinyatakan sebelumnya, jika parameter lpSecurityAttributes adalah NULL, handel yang dikembalikan oleh CreateFileTransacted tidak dapat diwariskan oleh proses anak apa pun yang dapat dibuat aplikasi Anda. Informasi berikut mengenai parameter ini juga berlaku:

  • Jika bInheritHandle bukan FALSE, yang merupakan nilai bukan nol, maka handel dapat diwariskan. Oleh karena itu sangat penting anggota struktur ini diinisialisasi dengan benar ke FALSE jika Anda tidak berniat menangani agar dapat diwariskan.
  • Daftar kontrol akses (ACL) dalam pendeskripsi keamanan default untuk file atau direktori diwarisi dari direktori induknya.
  • Sistem file target harus mendukung keamanan pada file dan direktori agar lpSecurityDescriptor memiliki efek pada file tersebut, yang dapat ditentukan dengan menggunakan GetVolumeInformation
Di Windows 8 dan Windows Server 2012, fungsi ini didukung oleh teknologi berikut.
Teknologi Didukung
Protokol Server Message Block (SMB) 3.0 Tidak
SMB 3.0 Transparent Failover (TFO) 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 menampilkan pesan bagi pengguna untuk memasukkan disk atau CD. Untuk mencegah sistem menampilkan pesan ini, panggil fungsi SetErrorMode dengan SEM_FAILCRITICALERRORS.

Untuk informasi selengkapnya, lihat Membuat dan Membuka File.

Jika Anda mengganti nama atau menghapus file lalu memulihkannya tak lama setelah itu, sistem akan mencari cache untuk informasi file yang akan dipulihkan. Informasi yang di-cache mencakup pasangan nama pendek/panjang dan waktu pembuatannya.

Jika Anda memanggil CreateFileTransacted pada file yang menunggu penghapusan sebagai akibat dari panggilan sebelumnya ke DeleteFile, fungsi gagal. Sistem operasi menunda penghapusan file hingga semua handel ke file ditutup. GetLastError mengembalikan ERROR_ACCESS_DENIED.

Parameter dwDesiredAccess bisa nol, memungkinkan aplikasi untuk mengkueri atribut file tanpa mengakses file jika aplikasi berjalan dengan pengaturan keamanan yang memadai. Ini berguna untuk menguji keberadaan file tanpa membukanya untuk akses baca dan/atau tulis, atau untuk mendapatkan statistik lain tentang file atau direktori. Lihat Mendapatkan dan Mengatur Informasi File dan GetFileInformationByHandle.

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 saat menulis ke file di seluruh jaringan terkadang 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.

Catatan

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

Persyaratan Nilai
Klien minimum yang didukung Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2008 [hanya aplikasi desktop]
Target Platform Windows
Header winbase.h (termasuk Windows.h)
Pustaka Kernel32.lib
DLL Kernel32.dll

Lihat juga

CloseHandle

CopyFileTransacted

CreateDirectoryTransacted

DeleteFileTransacted

Kompresi dan Dekompresi File

Enkripsi File

Fungsi Manajemen File

Keamanan File dan Hak Akses

Aliran File

FindFirstFileTransacted

Fungsi

GetFileAttributesTransacted

MoveFileTransacted

Topik Gambaran Umum

Pertimbangan Pemrograman untuk NTFS Transaksi

ReadFile

NTFS Transaksi (TxF)

WriteFile