MapViewOfFile3FromApp function (memoryapi.h)

Article
07/21/2023

Maps a view of a file mapping into the address space of a calling Windows Store app.

Using this function, you can: for new allocations, specify a range of virtual address space and a power-of-2 alignment restriction; specify an arbitrary number of extended parameters; specify a preferred NUMA node for the physical memory as an extended parameter; and specify a placeholder operation (specifically, replacement).

To specify the NUMA node, see the ExtendedParameters parameter.

Syntax

PVOID MapViewOfFile3FromApp(
  [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
);

Parameters

[in] FileMapping

A HANDLE to a section that is to be mapped into the address space of the specified process.

[in] Process

A HANDLE to a process into which the section will be mapped.

[in, optional] BaseAddress

The desired base address of the view. The address is rounded down to the nearest 64k boundary.

              If this parameter is <b>NULL</b>, the system picks the base
              address.

If BaseAddress is not NULL, then any provided MEM_ADDRESS_REQUIREMENTS structure must consist of all zeroes.

[in] Offset

The offset from the beginning of the section. This must be 64k aligned.

[in] ViewSize

The number of bytes to map. A value of zero (0) specifies that the entire section is to be mapped.

The size must always be a multiple of the page size.

[in] AllocationType

The type of memory allocation. This parameter can be zero (0) or one of the following values.

Value	Meaning
MEM_RESERVE 0x00002000	Maps a reserved view.
MEM_REPLACE_PLACEHOLDER 0x00004000	Replaces a placeholder with a mapped view. Only data/pf-backed section views are supported (no images, physical memory, etc.). When you replace a placeholder, BaseAddress and ViewSize must exactly match those of the placeholder, and any provided MEM_ADDRESS_REQUIREMENTS structure must consist of all zeroes. After you replace a placeholder with a mapped view, to free that mapped view back to a placeholder, see the UnmapFlags parameter of UnmapViewOfFileEx and UnmapViewOfFile2. A placeholder is a type of reserved memory region.
MEM_LARGE_PAGES 0x20000000	Maps a large page view. See large page support.

Value

Meaning

MEM_RESERVE
0x00002000

Maps a reserved view.

MEM_REPLACE_PLACEHOLDER
0x00004000

Replaces a placeholder with a mapped view. Only data/pf-backed section views are supported (no images, physical memory, etc.). When you replace a placeholder, BaseAddress and ViewSize must exactly match those of the placeholder, and any provided MEM_ADDRESS_REQUIREMENTS structure must consist of all zeroes.

After you replace a placeholder with a mapped view, to free that mapped view back to a placeholder, see the UnmapFlags parameter of UnmapViewOfFileEx and UnmapViewOfFile2.

A placeholder is a type of reserved memory region.

MEM_LARGE_PAGES
0x20000000

Maps a large page view. See large page support.

[in] PageProtection

The desired page protection.

For file-mapping objects created with the SEC_IMAGE attribute, the PageProtection parameter has no effect, and should be set to any valid value such as PAGE_READONLY.

[in, out, optional] ExtendedParameters

An optional pointer to one or more extended parameters of type MEM_EXTENDED_PARAMETER. Each of those extended parameter values can itself have a Type field of either MemExtendedParameterAddressRequirements or MemExtendedParameterNumaNode. If no MemExtendedParameterNumaNode extended parameter is provided, then the behavior is the same as for the VirtualAlloc/MapViewOfFile functions (that is, the preferred NUMA node for the physical pages is determined based on the ideal processor of the thread that first accesses the memory).

[in] ParameterCount

The number of extended parameters pointed to by ExtendedParameters.

Return value

Returns the base address of the mapped view, if successful. Otherwise, returns NULL and extended error status is available using GetLastError.

Remarks

This API helps support high-performance games, and server applications, which have particular requirements around managing their virtual address space. For example, mapping memory on top of a previously reserved region; this is useful for implementing an automatically wrapping ring buffer. And allocating memory with specific alignment; for example, to enable your application to commit large/huge page-mapped regions on demand.

With one important exception, file views derived from any file mapping object that is backed by the same file are coherent or identical at a specific time. Coherency is guaranteed for views within a process and for views that are mapped by different processes.

The exception is related to remote files. Although MapViewOfFile3FromApp works with remote files, it does not keep them coherent. For example, if two computers both map a file as writable, and both change the same page, each computer only sees its own writes to the page. When the data gets updated on the disk, it is not merged.

You can only successfully request executable protection if your app has the codeGeneration capability.

Examples

For a code example, see Scenario 1 in Virtual2Alloc.

Requirements

Requirement	Value
Minimum supported client	Windows 10 [desktop apps only]
Minimum supported server	Windows Server 2016 [desktop apps only]
Target Platform	Windows
Header	memoryapi.h (include Windows.h)
Library	WindowsApp.lib
DLL	Kernel32.dll