MapViewOfFileEx

LPVOID MapViewOfFileEx(hMapObject, fdwAccess, dwOffsetHigh, dwOffsetLow, cbMap, lpvBase)
HANDLE hMapObject;	/* file mapping object to map into address space	*/
DWORD fdwAccess;	/* desired access mode	*/
DWORD dwOffsetHigh;	/* high dword of file offset	*/
DWORD dwOffsetLow;	/* low dword of file offset	*/
DWORD cbMap;	/* number of bytes to map	*/
LPVOID lpvBase;	/* suggested start address for mapped view	*/

The MapViewOfFileEx function maps a view of a file into the address space of the calling process. This extended function allows the caller to specify a suggested memory address for the mapped view.

This function is available only in Win32/NT.

Parameters

hMapObject

Specifies an open handle to a file mapping object that is to be mapped into the caller's address space. The CreateFileMapping and OpenFileMapping functions return this handle.

fdwAccess

Specifies the access that is requested to the file mapping object. This determines the page protection of the pages mapped by the file. This parameter can be one of the following values:

Value

Meaning

FILE_MAP_WRITE
	Read and write access is desired. The mapping object must have been created with PAGE_READWRITE protection. hMapObject must have been created with FILE_MAP_WRITE access. A read and write view of the file will be mapped.
FILE_MAP_READ
	Read-only access is desired. The mapping object must have been created with PAGE_READWRITE or PAGE_READ protection. hMapObject must have been created with FILE_MAP_READ access. A read-only view of the file will be mapped.

dwOffsetHigh

Specifies the high-order 32 bits of the file offset where mapping is to begin.

dwOffsetLow

Specifies the low-order 32 bits of the file offset where mapping is to begin. The combination of the high and low offsets must specify a 64K aligned offset within the file, or the function will fail.

cbMap

Specifies the number of bytes of the file to map. If cbMap is zero, the entire file is mapped.

lpvBase

Points to the memory address (in the calling process' address space) where mapping should begin. Win32 rounds this address down to the nearest 64K boundary. If there is not enough address space at the specified address, the function will fail.

If lpvBase is NULL, Win32 chooses the mapping address. In this case, this function is equivalent to the MapViewOfFile function.

Return Value

The return value is the starting address of the mapped view if the function was successful, or NULL if an error occurred. Use the GetLastError function to obtain extended error information.

Comments

Mapping a file makes the specified portion of the file visible in the address space of the calling process.

If a suggested mapping address is supplied, the file will be mapped at the specified address (rounded down to the nearest 64K boundary) if there is enough address space at the specified address. If not, the function will fail.

Typically, the suggested address is used to specify that a file should be mapped at the same address in multiple processes. This requires that the region of address space must be available in all involved processes. No other memory allocation must take place in the region that will be used for mapping, including using the VirtualAlloc function to reserve memory.

Multiple views of a file (or a file mapping object and its mapped file) are said to be “coherent” if they contain identical data at a given time. This occurs if the file views are derived from the same file mapping object. A process can duplicate a file mapping object handle into another process with DuplicateHandle, or another process can open a file mapping object by name by using the OpenFileMapping function.

A mapped view of a file is not guaranteed to be coherent with a file being accessed via ReadFile or WriteFile.