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.

Sintaksis

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.

Nilai	Arti
FILE_MAP_ALL_ACCESS	Tampilan baca/tulis file dipetakan. Objek pemetaan file harus dibuat dengan perlindungan PAGE_READWRITE atau PAGE_EXECUTE_READWRITE. Saat digunakan dengan fungsi MapViewOfFile , 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 atau PAGE_EXECUTE_READWRITE. Ketika digunakan dengan MapViewOfFile, (FILE_MAP_WRITE \| FILE_MAP_READ) dan FILE_MAP_ALL_ACCESS setara dengan FILE_MAP_WRITE.

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

Nilai	Arti
FILE_MAP_COPY	Tampilan copy-on-write file dipetakan. Objek pemetaan file harus dibuat dengan perlindungan PAGE_READONLY, PAGE_EXECUTE_READ, PAGE_WRITECOPY, PAGE_EXECUTE_WRITECOPY, PAGE_READWRITE, atau PAGE_EXECUTE_READWRITE. Ketika proses menulis ke halaman copy-on-write, sistem menyalin halaman asli ke halaman baru yang bersifat privat untuk proses. Halaman baru didukung oleh file halaman. Perlindungan halaman baru berubah dari copy-on-write menjadi baca/tulis. Ketika akses copy-on-write ditentukan, sistem dan biaya penerapan 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 saat tampilan tidak dipetakan.
FILE_MAP_EXECUTE	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.
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 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.
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 tepat FILE_MAP_EXECUTE. 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 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 berurutan tinggi dari offset file tempat tampilan dimulai.

[in] dwFileOffsetLow

DWORD berurutan rendah dari offset file di mana tampilan akan dimulai. Kombinasi offset tinggi dan rendah harus menentukan offset dalam pemetaan file. Mereka juga harus cocok dengan granularitas alokasi memori virtual sistem. Artinya, offset harus kelipatan granularitas alokasi VirtualAlloc. Untuk mendapatkan granularitas alokasi memori VirtualAlloc dari 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 meluas dari offset yang ditentukan ke akhir pemetaan file.

Mengembalikan nilai

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

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

Komentar

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 petanya 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 yang ditentukan. 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 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 MapViewOfFile 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.

Tampilan file yang dipetakan tidak dijamin koheren dengan file yang sedang diakses oleh ReadFile atau fungsi WriteFile.

Jangan simpan penunjuk 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 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 dipesan 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_EXECUTEFILE_MAP_WRITE atau FILE_MAP_EXECUTEFILE_MAP_READ.

Di Windows Server 2012, fungsi ini didukung oleh teknologi berikut.

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Ya
Failover Transparan (TFO) SMB 3.0	Ya
SMB 3.0 dengan Scale-out File Shares (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

Syarat	Nilai
klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Platform Target	Windows
Header	memoryapi.h (termasuk Windows.h, Memoryapi.h)
Pustaka	onecore.lib
DLL	Kernel32.dll

Lihat juga

CreateFileMapping

Membuat Tampilan File

DuplicateHandle

GetSystemInfo

MapViewOfFileEx

Fungsi Manajemen Memori

OpenFileMapping

SYSTEM_INFO

UnmapViewOfFile

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2024-11-12