Fungsi MapViewOfFile (memoryapi.h)
Memetakan tampilan pemetaan file ke ruang alamat proses panggilan.
Untuk menentukan alamat dasar yang disarankan untuk tampilan, gunakan fungsi MapViewOfFileEx . Namun, praktik ini tidak disarankan.
Sintaks
LPVOID MapViewOfFile(
[in] HANDLE hFileMappingObject,
[in] DWORD dwDesiredAccess,
[in] DWORD dwFileOffsetHigh,
[in] DWORD dwFileOffsetLow,
[in] SIZE_T dwNumberOfBytesToMap
);
Parameter
[in] hFileMappingObject
Handel ke objek pemetaan file. Fungsi CreateFileMapping dan OpenFileMapping mengembalikan handel ini.
[in] dwDesiredAccess
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.
Dengan menggunakan bitwise OR, Anda dapat menggabungkan nilai di atas dengan nilai-nilai ini.
| Nilai | Makna |
|---|---|
|
Tampilan copy-on-write file dipetakan. Objek pemetaan file harus dibuat dengan perlindungan PAGE_READONLY, PAGE_READ_EXECUTE, PAGE_WRITECOPY, PAGE_EXECUTE_WRITECOPY, PAGE_READWRITE, atau PAGE_EXECUTE_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. |
|
Tampilan file yang dapat dieksekusi dipetakan (memori yang dipetakan dapat dijalankan sebagai kode). Objek pemetaan file harus dibuat dengan perlindungan PAGE_EXECUTE_READ, PAGE_EXECUTE_WRITECOPY, atau PAGE_EXECUTE_READWRITE .
Windows Server 2003 dan Windows XP: Nilai ini tersedia dimulai dengan Windows XP dengan SP2 dan Windows Server 2003 dengan SP1. |
|
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. Catatan: Pada versi OS sebelum Windows 10, versi 1703, bendera FILE_MAP_LARGE_PAGES tidak berpengaruh. Pada rilis ini, tampilan secara otomatis dipetakan menggunakan halaman besar jika bagian dibuat dengan set bendera SEC_LARGE_PAGES . |
|
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] dwFileOffsetHigh
DWORD urutan tinggi dari offset file tempat tampilan dimulai.
[in] dwFileOffsetLow
DWORD berurutan rendah dari offset file tempat tampilan akan dimulai. Kombinasi offset tinggi dan rendah 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] dwNumberOfBytesToMap
Jumlah byte pemetaan file untuk dipetakan ke tampilan. Semua byte harus dalam ukuran maksimum yang ditentukan oleh CreateFileMapping. 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
Pemetaan file membuat bagian file yang ditentukan terlihat di ruang alamat proses panggilan.
Untuk file yang lebih besar dari ruang alamat, Anda hanya dapat memetakan sebagian kecil data file pada satu waktu. Saat tampilan pertama selesai, Anda dapat membatalkan pemetaannya dan memetakan tampilan baru.
Untuk mendapatkan ukuran tampilan, gunakan fungsi VirtualQuery .
Beberapa tampilan file (atau objek pemetaan file dan file yang dipetakan) koheren jika berisi data yang identik pada waktu tertentu. Ini terjadi jika tampilan file berasal dari objek pemetaan file apa pun yang didukung oleh file yang sama. Proses dapat menduplikasi handel objek pemetaan file ke proses lain dengan menggunakan fungsi DuplicateHandle , atau proses lain dapat membuka objek pemetaan file berdasarkan nama dengan menggunakan fungsi OpenFileMapping .
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 MapViewOfFile berfungsi dengan file jarak jauh, MapViewOfFile 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.
Tampilan file yang dipetakan tidak dijamin koheren dengan file yang sedang diakses oleh fungsi ReadFile atau WriteFile .
Jangan menyimpan pointer dalam file yang dipetakan memori; menyimpan offset dari dasar pemetaan file sehingga pemetaan dapat digunakan di alamat apa pun.
Untuk melindungi dari pengecualian EXCEPTION_IN_PAGE_ERROR , gunakan penanganan pengecualian terstruktur untuk melindungi kode apa pun yang menulis ke atau membaca dari tampilan file yang dipetakan memori selain file halaman. Untuk informasi selengkapnya, lihat Membaca dan Menulis Dari Tampilan File.
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.
Jika objek pemetaan file didukung oleh file halaman (CreateFileMapping dipanggil dengan parameter hFile diatur ke INVALID_HANDLE_VALUE), file halaman harus cukup besar untuk menahan seluruh pemetaan. Jika tidak, MapViewOfFile gagal. Konten awal halaman dalam objek pemetaan file yang didukung oleh file halaman adalah 0 (nol).
Ketika objek pemetaan file yang didukung oleh file halaman dibuat, pemanggil dapat menentukan apakah MapViewOfFile harus memesan dan menerapkan halaman secara bersamaan (SEC_COMMIT) atau hanya memesan halaman (SEC_RESERVE). Pemetaan file membuat seluruh rentang alamat virtual yang dipetakan tidak tersedia untuk alokasi lain dalam proses. Setelah halaman dari rentang yang dipesan diterapkan, halaman tidak dapat dibebaskan atau dinonaktifkan dengan memanggil VirtualFree. Halaman yang dicadangkan dan diterapkan dirilis saat tampilan tidak dipetakan dan objek pemetaan file ditutup. Untuk detailnya, lihat fungsi UnmapViewOfFile dan CloseHandle .
Untuk memiliki file dengan izin yang dapat dieksekusi, aplikasi harus memanggil CreateFileMapping dengan PAGE_EXECUTE_READWRITE atau PAGE_EXECUTE_READ, lalu memanggil MapViewOfFile dengan FILE_MAP_WRITE FILE_MAP_EXECUTE | atauFILE_MAP_EXECUTE | FILE_MAP_READ.
Di Windows Server 2012, fungsi ini didukung oleh teknologi berikut.
| Teknologi | Didukung |
|---|---|
| Protokol Server Message Block (SMB) 3.0 | Ya |
| SMB 3.0 Transparent Failover (TFO) | Ya |
| SMB 3.0 dengan Berbagi File Peluasan Skala (SO) | Ya |
| Sistem File Volume Bersama Kluster (CsvFS) | Ya |
| Sistem File Tangguh (ReFS) | Ya |
Ketika CsvF dijeda, panggilan ini mungkin gagal dengan kesalahan yang menunjukkan bahwa ada konflik kunci.
Contoh
Misalnya, lihat Membuat Memori Bersama Bernama.
Persyaratan
| Klien minimum yang didukung | Windows XP [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2003 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | memoryapi.h (termasuk Windows.h, Memoryapi.h) |
| Pustaka | onecore.lib |
| DLL | Kernel32.dll |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk