Fungsi CreateFileFromAppW (fileapifromapp.h)

Membuat atau membuka file atau perangkat I/O. Perilaku fungsi ini identik dengan CreateFile, kecuali bahwa fungsi ini mematuhi model keamanan aplikasi Platform Windows Universal.

Sintaks

WINSTORAGEAPI HANDLE CreateFileFromAppW(
  LPCWSTR               lpFileName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                 dwCreationDisposition,
  DWORD                 dwFlagsAndAttributes,
  HANDLE                hTemplateFile
) noexcept;

Parameter

lpFileName

Nama file atau perangkat yang akan dibuat atau dibuka. Anda dapat menggunakan garis miring (/) atau garis miring terbelakang (\) dalam nama ini.

Dalam versi ANSI dari fungsi ini, namanya terbatas pada MAX_PATH karakter. Untuk memperpanjang batas ini hingga 32.767 karakter lebar, panggil versi Unicode fungsi dan tambahkan "\\?\" ke jalur. Untuk informasi selengkapnya, lihat Menamai File, Jalur, dan Namespace.

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.

Untuk versi unicode dari fungsi ini (CreateFileFromAppW), Anda dapat memilih untuk menghapus batasan MAX_PATH tanpa menambahkan awal "\\?\". Lihat bagian "Batasan Panjang Jalur Maksimum" dari Penamaan File, Jalur, dan Namespace untuk detailnya.

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 berkonflik dengan mode berbagi yang ditentukan oleh parameter dwShareMode dalam permintaan terbuka yang sudah memiliki handel terbuka.

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.

Nilai	Makna
0 0x00000000	Mencegah proses lain membuka file atau perangkat jika meminta akses hapus, baca, atau tulis.
0x00000004 FILE_SHARE_DELETE	Memungkinkan operasi terbuka berikutnya pada file atau perangkat untuk meminta akses penghapusan. Jika tidak, proses lain tidak dapat membuka file atau perangkat jika meminta akses penghapusan. Jika bendera ini tidak ditentukan, tetapi file atau perangkat telah dibuka untuk akses penghapusan, fungsi gagal. Catatan Akses penghapusan memungkinkan operasi hapus dan ganti nama.
0x00000001 FILE_SHARE_READ	Memungkinkan operasi terbuka berikutnya pada file atau perangkat untuk meminta akses baca. Jika tidak, proses lain tidak dapat membuka file atau perangkat jika meminta akses baca. Jika bendera ini tidak ditentukan, tetapi file atau perangkat telah dibuka untuk akses baca, fungsi gagal.
FILE_SHARE_WRITE 0x00000002	Memungkinkan operasi terbuka berikutnya pada file atau perangkat untuk meminta akses tulis. Jika tidak, proses lain tidak dapat membuka file atau perangkat jika meminta akses tulis. Jika bendera ini tidak ditentukan, tetapi file atau perangkat telah dibuka untuk akses tulis atau memiliki pemetaan file dengan akses tulis, fungsi gagal.

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 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 ADALAH NULL, file atau perangkat yang terkait dengan handel yang dikembalikan diberi pendeskripsi keamanan default.

Fungsi ini 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.

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 lebih lanjut, lihat bagian Keterangan.

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 atau perangkat yang ditentukan tidak ada, fungsi gagal dan kode kesalahan terakhir diatur ke ERROR_FILE_NOT_FOUND (2). Untuk informasi selengkapnya tentang perangkat, lihat bagian Keterangan.
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 .

dwFlagsAndAttributes

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.

Parameter ini juga dapat berisi kombinasi bendera (FILE_FLAG_*) untuk kontrol perilaku penembolokan file atau perangkat, mode akses, dan bendera tujuan khusus lainnya. Ini dikombinasikan dengan nilai FILE_ATTRIBUTE_* .

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.

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. Bendera ini tidak didukung pada Windows edisi Home, Home Premium, Starter, atau ARM.
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. Untuk informasi selengkapnya, lihat bagian Perilaku Penembolokan topik ini.

 

Bendera	Makna
0x02000000 FILE_FLAG_BACKUP_SEMANTICS	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.
0x04000000 FILE_FLAG_DELETE_ON_CLOSE	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.
0x20000000 FILE_FLAG_NO_BUFFERING	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 fungsi ini menggunakan bendera FILE_FLAG_NO_BUFFERING , untuk detailnya lihat Buffering File.
0x00100000 FILE_FLAG_OPEN_NO_RECALL	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.
0x00200000 FILE_FLAG_OPEN_REPARSE_POINT	Pemrosesan titik pemilah ulang normal tidak akan terjadi; fungsi ini akan mencoba membuka titik pemilah ulang. 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. Untuk informasi lebih lanjut, lihat bagian Keterangan.
0x40000000 FILE_FLAG_OVERLAPPED	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 sinyal. 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.
0x0100000 FILE_FLAG_POSIX_SEMANTICS	Akses akan terjadi 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.
0x10000000 FILE_FLAG_RANDOM_ACCESS	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.
0x00800000 FILE_FLAG_SESSION_AWARE	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.
0x08000000 FILE_FLAG_SEQUENTIAL_SCAN	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 terbalik) 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.
0x80000000 FILE_FLAG_WRITE_THROUGH	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.

 

Parameter dwFlagsAndAttributesjuga dapat menentukan informasi SQOS. 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 .

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, parameter ini diabaikan.

Saat membuka file terenkripsi baru, file mewarisi daftar kontrol akses diskresi dari direktori induknya. Untuk informasi selengkapnya, lihat Enkripsi File.

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.

Persyaratan

Klien minimum yang didukung	Windows 10, versi 1803
Header	fileapifromapp.h