Fungsi MapViewOfFile3 (memoryapi.h)

Artikel
06/27/2024

Memetakan tampilan file atau bagian yang didukung pagefile ke ruang alamat proses yang ditentukan.

Sintaksis

PVOID MapViewOfFile3(
  [in]                HANDLE                 FileMapping,
  [in]                HANDLE                 Process,
  [in, optional]      PVOID                  BaseAddress,
  [in]                ULONG64                Offset,
  [in]                SIZE_T                 ViewSize,
  [in]                ULONG                  AllocationType,
  [in]                ULONG                  PageProtection,
  [in, out, optional] MEM_EXTENDED_PARAMETER *ExtendedParameters,
  [in]                ULONG                  ParameterCount
);

Parameter

[in] FileMapping

HANDLE ke bagian yang akan dipetakan ke ruang alamat proses yang ditentukan.

[in] Process

HANDLE ke proses di mana bagian akan dipetakan.

[in, optional] BaseAddress

Alamat dasar tampilan yang diinginkan (alamat dibulatkan ke bawah ke batas 64k terdekat).

Jika parameter ini NULL, sistem akan memilih alamat dasar.

Jika baseAddress tidak null, maka setiap MEM_ADDRESS_REQUIREMENTS yang disediakan harus terdiri dari semua nol.

[in] Offset

Offset dari awal bagian.

Offset harus selaras 64k.

[in] ViewSize

Jumlah byte yang akan dipetakan. Nilai nol (0) menentukan bahwa seluruh bagian akan dipetakan.

Ukuran harus selalu kelipatan ukuran halaman.

[in] AllocationType

Jenis alokasi memori. Parameter ini bisa nol (0) atau salah satu nilai berikut.

Nilai	Arti
MEM_RESERVE 0x00002000	Memetakan tampilan yang dipesan.
MEM_REPLACE_PLACEHOLDER 0x00004000	Mengganti tempat penampung dengan tampilan yang dipetakan. Hanya tampilan bagian yang didukung data/pf yang didukung (tidak ada gambar, memori fisik, dll.). Saat Anda mengganti tempat penampung, BaseAddress dan ViewSize harus sama persis dengan tempat penampung, dan struktur MEM_ADDRESS_REQUIREMENTS yang disediakan harus terdiri dari semua nol. Setelah Anda mengganti tempat penampung dengan tampilan yang dipetakan, untuk membebaskan tampilan yang dipetakan kembali ke tempat penampung, lihat parameter UnmapFlags UnmapViewOfFileEx dan UnmapViewOfFile2. Tempat penampung adalah jenis wilayah memori yang dipesan. Persyaratan perataan 64k pada Offset dan BaseAddress tidak berlaku saat bendera ini ditentukan.
MEM_LARGE_PAGES 0x20000000	Memetakan tampilan halaman besar. 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 parameter BaseAddress , maka nilainya harus kelipatan GetLargePageMinimum.

Nilai

Arti

MEM_RESERVE
0x00002000

Memetakan tampilan yang dipesan.

MEM_REPLACE_PLACEHOLDER
0x00004000

Mengganti tempat penampung dengan tampilan yang dipetakan. Hanya tampilan bagian yang didukung data/pf yang didukung (tidak ada gambar, memori fisik, dll.). Saat Anda mengganti tempat penampung, BaseAddress dan ViewSize harus sama persis dengan tempat penampung, dan struktur MEM_ADDRESS_REQUIREMENTS yang disediakan harus terdiri dari semua nol.

Setelah Anda mengganti tempat penampung dengan tampilan yang dipetakan, untuk membebaskan tampilan yang dipetakan kembali ke tempat penampung, lihat parameter UnmapFlags UnmapViewOfFileEx dan UnmapViewOfFile2.

Tempat penampung adalah jenis wilayah memori yang dipesan.

Persyaratan perataan 64k pada Offset dan BaseAddress tidak berlaku saat bendera ini ditentukan.

MEM_LARGE_PAGES
0x20000000

Memetakan tampilan halaman besar. 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 parameter BaseAddress , maka nilainya harus kelipatan GetLargePageMinimum.

[in] PageProtection

Perlindungan halaman yang diinginkan.

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

[in, out, optional] ExtendedParameters

Penunjuk opsional ke satu atau beberapa parameter jenis yang diperluas MEM_EXTENDED_PARAMETER. Masing-masing nilai parameter yang diperluas itu sendiri dapat memiliki bidang Jenis dari MemExtendedParameterAddressRequirements atau MemExtendedParameterNumaNode. Jika tidak ada parameter MemExtendedParameterNumaNode diperluas yang disediakan, maka perilakunya sama dengan untuk VirtualAlloc/fungsi MapViewOfFile (yaitu, simpul NUMA pilihan untuk halaman fisik ditentukan berdasarkan prosesor ideal utas yang pertama kali mengakses memori).

[in] ParameterCount

Jumlah parameter yang diperluas yang diacu oleh ExtendedParameters.

Mengembalikan nilai

Mengembalikan alamat dasar tampilan yang dipetakan, jika berhasil. Jika tidak, mengembalikan NULL dan status kesalahan yang diperluas tersedia menggunakan GetLastError.

Komentar

API ini membantu mendukung game berkinerja tinggi, dan aplikasi server, yang memiliki persyaratan khusus sekeliling mengelola ruang alamat virtual mereka. Misalnya, memetakan memori di atas wilayah yang dipesan sebelumnya; ini berguna untuk menerapkan buffer cincin pembungkusan secara otomatis. Dan mengalokasikan memori dengan perataan tertentu; misalnya, untuk memungkinkan aplikasi Anda menerapkan wilayah besar/besar yang dipetakan halaman sesuai permintaan.

Dengan menggunakan fungsi ini untuk alokasi baru, Anda dapat:

tentukan rentang ruang alamat virtual dan pembatasan perataan power-of-2
tentukan jumlah arbitrer parameter yang diperluas
tentukan simpul NUMA pilihan untuk memori fisik sebagai parameter yang diperluas
tentukan operasi tempat penampung (khususnya, penggantian).

Untuk menentukan simpul NUMA, lihat parameter ExtendedParameters.

Contoh

Untuk contoh kode, lihat Skenario 1 di VirtualAlloc2.

Persyaratan

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