Fungsi MapViewOfFileFromApp (memoryapi.h)

Artikel
03/11/2023

Memetakan tampilan pemetaan file ke ruang alamat aplikasi Windows Store panggilan.

Sintaks

PVOID MapViewOfFileFromApp(
  [in] HANDLE  hFileMappingObject,
  [in] ULONG   DesiredAccess,
  [in] ULONG64 FileOffset,
  [in] SIZE_T  NumberOfBytesToMap
);

Parameter

[in] hFileMappingObject

Handel ke objek pemetaan file. Fungsi CreateFileMappingFromApp mengembalikan handel ini.

[in] DesiredAccess

Jenis akses ke objek pemetaan file, yang menentukan perlindungan halaman halaman. Parameter ini bisa menjadi salah satu nilai berikut, atau kombinasi bitwise OR dari beberapa nilai jika sesuai.

Nilai	Makna
FILE_MAP_ALL_ACCESS	Tampilan baca/tulis file dipetakan. Objek pemetaan file harus dibuat dengan perlindungan PAGE_READWRITE . Saat digunakan dengan MapViewOfFileFromApp, FILE_MAP_ALL_ACCESS setara dengan FILE_MAP_WRITE.
FILE_MAP_READ	Tampilan baca-saja dari file dipetakan. Upaya untuk menulis ke tampilan file menghasilkan pelanggaran akses. Objek pemetaan file harus dibuat dengan perlindungan PAGE_READONLY, PAGE_READWRITE, PAGE_EXECUTE_READ, atau PAGE_EXECUTE_READWRITE .
FILE_MAP_WRITE	Tampilan baca/tulis file dipetakan. Objek pemetaan file harus dibuat dengan perlindungan PAGE_READWRITE . Saat digunakan dengan MapViewOfFileFromApp, `(FILE_MAP_WRITE \| FILE_MAP_READ)` setara dengan FILE_MAP_WRITE.

Dengan menggunakan bitwise OR, Anda dapat menggabungkan nilai di atas dengan nilai-nilai ini.

Nilai	Makna
FILE_MAP_COPY	Tampilan copy-on-write file dipetakan. Objek pemetaan file harus dibuat dengan perlindungan PAGE_READONLY, PAGE_READ_EXECUTE, PAGE_WRITECOPY, atau PAGE_READWRITE . Saat proses menulis ke halaman copy-on-write, sistem menyalin halaman asli ke halaman baru yang bersifat privat untuk proses tersebut. Halaman baru didukung oleh file halaman. Perlindungan halaman baru berubah dari copy-on-write menjadi baca/tulis. Ketika akses copy-on-write ditentukan, biaya penerapan sistem dan proses yang diambil adalah untuk seluruh tampilan karena proses panggilan berpotensi menulis ke setiap halaman dalam tampilan, membuat semua halaman privat. Konten halaman baru tidak pernah ditulis kembali ke file asli dan hilang ketika tampilan tidak dipetakan.
FILE_MAP_LARGE_PAGES	Dimulai dengan Windows 10, versi 1703, bendera ini menentukan bahwa tampilan harus dipetakan menggunakan dukungan halaman besar. Ukuran tampilan harus kelipatan dari ukuran halaman besar yang dilaporkan oleh fungsi GetLargePageMinimum , dan objek pemetaan file harus dibuat menggunakan opsi SEC_LARGE_PAGES . Jika Anda memberikan nilai non-null untuk lpBaseAddress, maka nilainya harus kelipatan GetLargePageMinimum.
FILE_MAP_TARGETS_INVALID	Mengatur semua lokasi dalam file yang dipetakan sebagai target yang tidak valid untuk Control Flow Guard (CFG). Bendera ini mirip dengan PAGE_TARGETS_INVALID. Gunakan bendera ini dalam kombinasi dengan akses eksekusi FILE_MAP_EXECUTE kanan. Setiap panggilan tidak langsung ke lokasi di halaman tersebut akan gagal pemeriksaan CFG, dan prosesnya akan dihentikan. Perilaku default untuk halaman yang dapat dieksekusi yang dialokasikan adalah ditandai sebagai target panggilan yang valid untuk CFG.

Nilai

Makna

FILE_MAP_COPY

Tampilan copy-on-write file dipetakan. Objek pemetaan file harus dibuat dengan perlindungan PAGE_READONLY, PAGE_READ_EXECUTE, PAGE_WRITECOPY, atau PAGE_READWRITE .

Saat proses menulis ke halaman copy-on-write, sistem menyalin halaman asli ke halaman baru yang bersifat privat untuk proses tersebut. Halaman baru didukung oleh file halaman. Perlindungan halaman baru berubah dari copy-on-write menjadi baca/tulis.

Ketika akses copy-on-write ditentukan, biaya penerapan sistem dan proses yang diambil adalah untuk seluruh tampilan karena proses panggilan berpotensi menulis ke setiap halaman dalam tampilan, membuat semua halaman privat. Konten halaman baru tidak pernah ditulis kembali ke file asli dan hilang ketika tampilan tidak dipetakan.

FILE_MAP_LARGE_PAGES

Dimulai dengan Windows 10, versi 1703, bendera ini menentukan bahwa tampilan harus dipetakan menggunakan dukungan halaman besar. Ukuran tampilan harus kelipatan dari ukuran halaman besar yang dilaporkan oleh fungsi GetLargePageMinimum , dan objek pemetaan file harus dibuat menggunakan opsi SEC_LARGE_PAGES . Jika Anda memberikan nilai non-null untuk lpBaseAddress, maka nilainya harus kelipatan GetLargePageMinimum.

FILE_MAP_TARGETS_INVALID

Mengatur semua lokasi dalam file yang dipetakan sebagai target yang tidak valid untuk Control Flow Guard (CFG). Bendera ini mirip dengan PAGE_TARGETS_INVALID. Gunakan bendera ini dalam kombinasi dengan akses eksekusi FILE_MAP_EXECUTE kanan. Setiap panggilan tidak langsung ke lokasi di halaman tersebut akan gagal pemeriksaan CFG, dan prosesnya akan dihentikan. Perilaku default untuk halaman yang dapat dieksekusi yang dialokasikan adalah ditandai sebagai target panggilan yang valid untuk CFG.

Untuk objek pemetaan file yang dibuat dengan atribut SEC_IMAGE , parameter dwDesiredAccess tidak berpengaruh, dan harus diatur ke nilai yang valid seperti FILE_MAP_READ.

Untuk informasi selengkapnya tentang akses ke objek pemetaan file, lihat Keamanan Pemetaan File dan Hak Akses.

[in] FileOffset

Offset file di mana tampilan akan dimulai. Offset harus menentukan offset dalam pemetaan file. Mereka juga harus cocok dengan granularitas alokasi memori sistem. Artinya, offset harus kelipatan granularitas alokasi. Untuk mendapatkan granularitas alokasi memori sistem, gunakan fungsi GetSystemInfo , yang mengisi anggota struktur SYSTEM_INFO .

[in] NumberOfBytesToMap

Jumlah byte pemetaan file untuk dipetakan ke tampilan. Semua byte harus dalam ukuran maksimum yang ditentukan oleh CreateFileMappingFromApp. Jika parameter ini adalah 0 (nol), pemetaan diperluas dari offset yang ditentukan ke akhir pemetaan file.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah alamat awal tampilan yang dipetakan.

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

Keterangan

Dengan satu pengecualian penting, tampilan file yang berasal dari objek pemetaan file apa pun yang didukung oleh file yang sama bersifat koheren 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 MapViewOfFileFromApp berfungsi dengan file jarak jauh, mapViewOfFileFromApp 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.

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

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8 [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2012 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	memoryapi.h (termasuk Windows.h)
Pustaka	onecore.lib
DLL	Kernel32.dll