Bagikan melalui

Fungsi CreateFileMappingFromApp (memoryapi.h)

Membuat atau membuka objek pemetaan file bernama atau tidak bernama untuk file tertentu dari aplikasi Bursa Windows.

Sintaksis

HANDLE CreateFileMappingFromApp(
  [in]           HANDLE               hFile,
  [in, optional] PSECURITY_ATTRIBUTES SecurityAttributes,
  [in]           ULONG                PageProtection,
  [in]           ULONG64              MaximumSize,
  [in, optional] PCWSTR               Name
);

Parameter

[in] hFile

Handel ke file untuk membuat objek pemetaan file.

File harus dibuka dengan hak akses yang kompatibel dengan bendera perlindungan yang ditentukan parameter flProtect. Ini tidak diperlukan, tetapi disarankan agar file yang ingin Anda petakan dibuka untuk akses eksklusif. Untuk informasi selengkapnya, lihat Keamanan File dan Hak Akses.

Jika hFile INVALID_HANDLE_VALUE, proses panggilan juga harus menentukan ukuran untuk objek pemetaan file di parameter dwMaximumSizeHigh dan dwMaximumSizeLow. Dalam skenario ini, CreateFileMappingFromApp membuat objek pemetaan file dengan ukuran tertentu yang didukung oleh file halaman sistem alih-alih oleh file dalam sistem file.

[in, optional] SecurityAttributes

Penunjuk ke struktur SECURITY_ATTRIBUTES yang menentukan apakah handel yang dikembalikan dapat diwariskan oleh proses turunan. lpSecurityDescriptor anggota struktur SECURITY_ATTRIBUTES menentukan deskriptor keamanan untuk objek pemetaan file baru.

Jika SecurityAttributesNULL, handel tidak dapat diwariskan dan objek pemetaan file mendapatkan deskriptor keamanan default. Daftar kontrol akses (ACL) dalam deskriptor keamanan default untuk objek pemetaan file berasal dari token utama atau peniruan identitas pembuat. Untuk informasi selengkapnya, lihat Keamanan Pemetaan File dan Hak Akses.

[in] PageProtection

Menentukan perlindungan halaman objek pemetaan file. Semua tampilan objek yang dipetakan harus kompatibel dengan perlindungan ini.

Parameter ini bisa menjadi salah satu nilai berikut.

Nilai Arti
PAGE_READONLY
0x02
 Memungkinkan tampilan dipetakan untuk akses baca-saja atau salin-saat-tulis. Upaya untuk menulis ke wilayah tertentu menghasilkan pelanggaran akses.

Handel file yang ditentukan parameter hFile harus dibuat dengan hak akses GENERIC_READ.
PAGE_READWRITE
0x04
 Memungkinkan tampilan dipetakan untuk akses baca-saja, salin-tulis, atau baca/tulis.

Handel file yang ditentukan parameter hFile harus dibuat dengan hak akses GENERIC_READ dan GENERIC_WRITE.
PAGE_WRITECOPY
0x08
 Memungkinkan tampilan dipetakan untuk akses baca-saja atau salin-saat-tulis. Nilai ini setara dengan PAGE_READONLY.

Handel file yang ditentukan parameter hFile harus dibuat dengan hak akses GENERIC_READ.
 

Aplikasi dapat menentukan satu atau beberapa atribut berikut untuk objek pemetaan file dengan menggabungkannya dengan salah satu nilai perlindungan halaman sebelumnya.

Nilai Arti
SEC_COMMIT
0x8000000
 Jika objek pemetaan file didukung oleh file halaman sistem operasi (parameter hfile INVALID_HANDLE_VALUE), menentukan bahwa ketika tampilan file dipetakan ke dalam ruang alamat proses, seluruh rentang halaman diterapkan daripada yang dicadangkan. Sistem harus memiliki cukup halaman yang dapat dikomit untuk menahan seluruh pemetaan. Jika tidak, CreateFileMappingFromApp gagal.

Atribut ini tidak berpengaruh untuk objek pemetaan file yang didukung oleh file gambar atau file data yang dapat dieksekusi (parameter hfile adalah handel ke file).

SEC_COMMIT tidak dapat dikombinasikan dengan SEC_RESERVE.

Jika tidak ada atribut yang ditentukan, SEC_COMMIT diasumsikan.
SEC_IMAGE_NO_EXECUTE
0x11000000
 Menentukan bahwa file yang ditentukan parameter hFile adalah file gambar yang dapat dieksekusi yang tidak akan dijalankan dan file gambar yang dimuat tidak akan memiliki pemeriksaan integritas paksa yang dijalankan. Selain itu, pemetaan tampilan objek pemetaan file yang dibuat dengan atribut SEC_IMAGE_NO_EXECUTE tidak akan memanggil panggilan balik driver yang terdaftar menggunakan PsSetLoadImageNotifyRoutine API kernel.

Atribut SEC_IMAGE_NO_EXECUTE harus dikombinasikan dengan nilai perlindungan halaman PAGE_READONLY. Tidak ada atribut lain yang valid dengan SEC_IMAGE_NO_EXECUTE.
SEC_LARGE_PAGES
0x80000000
 Memungkinkan halaman besar digunakan untuk objek pemetaan file yang didukung oleh file halaman sistem operasi (parameter hfileINVALID_HANDLE_VALUE). Atribut ini tidak didukung untuk objek pemetaan file yang didukung oleh file gambar atau file data yang dapat dieksekusi (parameter hFile adalah handel ke gambar atau file data yang dapat dieksekusi).

Ukuran maksimum objek pemetaan file harus kelipatan ukuran minimum halaman besar yang dikembalikan oleh fungsi GetLargePageMinimum. Jika tidak, CreateFileMappingFromApp gagal. Saat memetakan tampilan objek pemetaan file yang dibuat dengan SEC_LARGE_PAGES, alamat dasar dan ukuran tampilan juga harus kelipatan dari ukuran halaman besar minimum.

SEC_LARGE_PAGES mengharuskan hak istimewa SeLockMemoryPrivilege diaktifkan dalam token pemanggil.

Jika SEC_LARGE_PAGES ditentukan, SEC_COMMIT juga harus ditentukan.
SEC_NOCACHE
0x10000000
 Mengatur semua halaman agar tidak dapat di-cache.

Aplikasi tidak boleh menggunakan atribut ini kecuali jika diperlukan secara eksplisit untuk perangkat. Menggunakan fungsi yang saling mengunci dengan memori yang dipetakan dengan SEC_NOCACHE dapat menghasilkan pengecualian EXCEPTION_ILLEGAL_INSTRUCTION.

SEC_NOCACHE mengharuskan atribut SEC_RESERVE atau SEC_COMMIT diatur.
SEC_RESERVE
0x4000000
 Jika objek pemetaan file didukung oleh file halaman sistem operasi (parameter hfile INVALID_HANDLE_VALUE), menentukan bahwa ketika tampilan file dipetakan ke dalam ruang alamat proses, seluruh rentang halaman dicadangkan untuk digunakan nanti oleh proses daripada diterapkan.

Halaman yang dipesan dapat dilakukan dalam panggilan berikutnya ke fungsi VirtualAlloc. Setelah halaman diterapkan, halaman tidak dapat dibebaskan atau dinonaktifkan dengan fungsi VirtualFree.

Atribut ini tidak berpengaruh untuk objek pemetaan file yang didukung oleh file gambar atau file data yang dapat dieksekusi (parameter hfile adalah handel ke file).

SEC_RESERVE tidak dapat dikombinasikan dengan SEC_COMMIT.
SEC_WRITECOMBINE
0x40000000
 Mengatur semua halaman yang akan digabungkan dengan tulis.

Aplikasi tidak boleh menggunakan atribut ini kecuali jika diperlukan secara eksplisit untuk perangkat. Menggunakan fungsi yang saling mengunci dengan memori yang dipetakan dengan SEC_WRITECOMBINE dapat menghasilkan pengecualian EXCEPTION_ILLEGAL_INSTRUCTION.

SEC_WRITECOMBINE mengharuskan atribut SEC_RESERVE atau SEC_COMMIT diatur.

[in] MaximumSize

Ukuran maksimum objek pemetaan file.

Upaya untuk memetakan file dengan panjang 0 (nol) gagal dengan kode kesalahan ERROR_FILE_INVALID. Aplikasi harus menguji file dengan panjang 0 (nol) dan menolak file-file tersebut.

[in, optional] Name

Nama objek pemetaan file.

Jika parameter ini cocok dengan nama objek pemetaan yang ada, fungsi meminta akses ke objek dengan perlindungan yang flProtect tentukan.

Jika parameter ini NULL, objek pemetaan file dibuat tanpa nama.

Jika lpName cocok dengan nama peristiwa, semaphore, mutex, timer yang dapat ditunda, atau objek pekerjaan yang ada, fungsi gagal, dan fungsi GetLastError mengembalikan ERROR_INVALID_HANDLE. Ini terjadi karena objek ini memiliki namespace yang sama.

Nama dapat memiliki awalan "Global" atau "Lokal" untuk secara eksplisit membuat objek di namespace layanan global atau sesi. Sisa nama dapat berisi karakter apa pun kecuali karakter garis miring terbelakang (\). Membuat objek pemetaan file di namespace layanan global dari sesi selain sesi nol memerlukan hak istimewa SeCreateGlobalPrivilege. Untuk informasi selengkapnya, lihat Namespace Objek Kernel.

Peralihan pengguna cepat diimplementasikan dengan menggunakan sesi Layanan Terminal. Pengguna pertama yang masuk menggunakan sesi 0 (nol), pengguna berikutnya untuk masuk menggunakan sesi 1 (satu), dan sebagainya. Nama objek kernel harus mengikuti panduan yang diuraikan untuk Layanan Terminal sehingga aplikasi dapat mendukung beberapa pengguna.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke objek pemetaan file yang baru dibuat.

Jika objek ada sebelum panggilan fungsi, fungsi mengembalikan handel ke objek yang ada (dengan ukurannya saat ini, bukan ukuran yang ditentukan), dan GetLastError mengembalikan ERROR_ALREADY_EXISTS.

Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.

Komentar

Setelah objek pemetaan file dibuat, ukuran file tidak boleh melebihi ukuran objek pemetaan file; jika ya, tidak semua isi file tersedia untuk dibagikan.

Jika aplikasi menentukan ukuran untuk objek pemetaan file yang lebih besar dari ukuran file bernama aktual pada disk dan jika perlindungan halaman memungkinkan akses tulis (yaitu, parameter flProtect menentukan PAGE_READWRITE), maka file pada disk ditingkatkan agar sesuai dengan ukuran objek pemetaan file yang ditentukan. Jika file diperluas, konten file antara akhir lama file dan akhir baru file tidak dijamin nol; perilaku didefinisikan oleh sistem file. Jika file pada disk tidak dapat ditingkatkan, CreateFileMappingFromApp gagal dan GetLastError mengembalikan ERROR_DISK_FULL.

Konten awal halaman dalam objek pemetaan file yang didukung oleh file halaman sistem operasi adalah 0 (nol).

Handel yang createFileMappingFromApp mengembalikan memiliki akses penuh ke objek pemetaan file baru, dan dapat digunakan dengan fungsi apa pun yang memerlukan handel ke objek pemetaan file.

Beberapa proses dapat berbagi tampilan file yang sama dengan menggunakan satu objek pemetaan file bersama atau membuat objek pemetaan file terpisah yang didukung oleh file yang sama. Objek pemetaan file tunggal dapat dibagikan oleh beberapa proses melalui pewarisan handel pada pembuatan proses, menduplikasi handel, atau membuka objek pemetaan file berdasarkan nama. Untuk informasi selengkapnya, lihat fungsi CreateProcess, DuplicateHandle dan OpenFileMapping.

Membuat objek pemetaan file tidak benar-benar memetakan tampilan ke ruang alamat proses. Fungsi MapViewOfFileEx memetakan tampilan file ke ruang alamat proses.

Dengan satu pengecualian penting, tampilan file yang berasal dari objek pemetaan file apa pun yang didukung oleh file yang sama melekat atau identik pada waktu tertentu. Koherensi dijamin untuk tampilan dalam proses dan untuk tampilan yang dipetakan oleh proses yang berbeda.

Pengecualian terkait dengan file jarak jauh. Meskipun CreateFileMappingFromApp bekerja dengan file jarak jauh, itu tidak membuatnya tetap koheren. Misalnya, jika dua komputer memetakan file sebagai dapat ditulis, dan keduanya mengubah halaman yang sama, setiap komputer hanya melihat tulisannya sendiri ke halaman. Ketika data diperbarui pada disk, data tidak digabungkan.

File yang dipetakan dan file yang diakses dengan menggunakan fungsi input dan output (I/O) ( ReadFile dan WriteFile) belum tentu koheren.

Tampilan objek pemetaan file yang dipetakan mempertahankan referensi internal ke objek, dan objek pemetaan file tidak ditutup sampai semua referensi ke objek tersebut dirilis. Oleh karena itu, untuk sepenuhnya menutup objek pemetaan file, aplikasi harus membatalkan peta semua tampilan objek pemetaan file dengan memanggil UnmapViewOfFile dan menutup handel objek pemetaan file dengan memanggil CloseHandle. Fungsi-fungsi ini dapat dipanggil dalam urutan apa pun.

Saat memodifikasi file melalui tampilan yang dipetakan, tanda waktu modifikasi terakhir mungkin tidak diperbarui secara otomatis. Jika diperlukan, pemanggil harus menggunakan SetFileTime untuk mengatur tanda waktu.

Gunakan penanganan pengecualian terstruktur untuk melindungi kode apa pun yang menulis atau membaca dari tampilan file. Untuk informasi selengkapnya, lihat Membaca dan Menulis Dari Tampilan File.

Anda hanya dapat berhasil meminta perlindungan yang dapat dieksekusi jika aplikasi Anda memiliki kemampuan codeGeneration.

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 memoryapi.h (termasuk Windows.h)
Pustaka onecore.lib
DLL Kernel32.dll

Lihat juga

closeHandle

CreateFileMapping

Membuat Objek Pemetaan File

DuplicateHandle

Fungsi Pemetaan File

MapViewOfFile

MapViewOfFileEx

Fungsi Manajemen Memori

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAlloc

WriteFile

  • Last updated on