Bagikan melalui

Fungsi CreateFile2FromAppW (fileapifromapp.h)

  • Artikel

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

Sintaks

WINSTORAGEAPI HANDLE CreateFile2FromAppW(
  LPCWSTR                           lpFileName,
  DWORD                             dwDesiredAccess,
  DWORD                             dwShareMode,
  DWORD                             dwCreationDisposition,
  LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
) noexcept;

Parameter

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.

Untuk informasi tentang memilih keluar dari batasan MAX_PATH tanpa menambahkan "\\?\", 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.

Jika parameter ini nol dan fungsi berhasil, file atau perangkat tidak dapat dibagikan dan tidak dapat dibuka lagi sampai handel ke file atau perangkat ditutup. Untuk informasi lebih lanjut, lihat bagian Keterangan.

Anda tidak dapat meminta mode berbagi yang berkonflik dengan mode akses yang ditentukan dalam permintaan yang sudah ada yang memiliki handel terbuka. Fungsi ini 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 dwDesiredAccess , lihat Membuat dan Membuka File.

Catatan Opsi berbagi untuk setiap handel terbuka tetap berlaku hingga handel tersebut ditutup, terlepas dari konteks proses.

 

Nilai Makna
0 0x00000000

Mencegah proses lain membuka file atau perangkat jika meminta akses hapus, baca, atau tulis. Akses eksklusif ke file atau direktori hanya diberikan jika aplikasi memiliki akses tulis ke file.
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.

Jika file atau direktori sedang dibuka dan bendera ini tidak ditentukan, dan pemanggil tidak memiliki akses tulis ke file atau direktori, 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.

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.

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

pCreateExParams

Penunjuk ke struktur CREATEFILE2_EXTENDED_PARAMETERS opsional.

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

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