MapViewOfFileEx
The MapViewOfFileEx
function maps a view of a file into the address space of the calling process.
This extended function allows the calling process to specify a suggested memory
address for the mapped view.
This function
is available for Win32-based applications only.
LPVOID MapViewOfFileEx(
|
HANDLE hFileMappingObject, |
// file-mapping
object to map into address space |
|
DWORD dwDesiredAccess, |
// access mode |
|
DWORD dwFileOffsetHigh, |
// high-order 32
bits of file offset |
|
DWORD dwFileOffsetLow, |
// low-order 32
bits of file offset |
|
DWORD dwNumberOfBytesToMap, |
// number of bytes
to map |
|
LPVOID lpBaseAddress |
// suggested
starting address for mapped view |
|
); |
|
Parameters
hFileMappingObject
Identifies an
open handle to a file-mapping object. The CreateFileMapping and OpenFileMapping functions return this
handle.
dwDesiredAccess
Specifies the
type of access to the file-mapping object and, therefore, 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. The hFileMappingObject parameter must have been created with
PAGE_READWRITE protection. A read-write view of the file is mapped. |
|
FILE_MAP_READ |
Read-only
access. The hFileMappingObject parameter must have been created with
PAGE_READWRITE or PAGE_READONLY protection. A read-only view of the file is
mapped. |
|
FILE_MAP_ALL_ACCESS |
Same as
FILE_MAP_WRITE. |
|
FILE_MAP_COPY |
Copy on
write access. If you create the map with PAGE_WRITECOPY and the view with
FILE_MAP_COPY, you will receive a view to the file. If you write to it, the
pages are automatically swappable and the modifications you make will not go
to the original data file. Windows
95: You must pass PAGE_WRITECOPY to
CreateFileMapping;
otherwise, an error will be returned. If you
share the mapping between multiple processes using DuplicateHandle or OpenFileMapping and one process writes to
a view, the modification is propagated to the other process. The original
file does not change. Windows
NT: There is no restriction as to
how the hFileMappingObject parameter must be created. Copy on write is
valid for any type of view. If you
share the mapping between multiple processes using DuplicateHandle or OpenFileMapping and one process writes to
a view, the modification is not propagated to the other process. The original
file does not change. |
dwFileOffsetHigh
Specifies the
high-order 32 bits of the file offset where mapping is to begin.
dwFileOffsetLow
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 an offset within the file that matches
the system s memory allocation granularity, or the function fails. That is, the
offset must be a multiple of the allocation granularity. Use the GetSystemInfo function, which fills in
the members of a SYSTEM_INFO
structure, to obtain the system s memory allocation granularity.
dwNumberOfBytesToMap
Specifies the
number of bytes of the file to map. If dwNumberOfBytesToMap is zero, the
entire file is mapped.
lpBaseAddress
Points to the
memory address in the calling process s address space where mapping should
begin. This must be a multiple of the system s memory allocation granularity,
or the function fails. Use the GetSystemInfoNH29XO function, which fills in the members of a SYSTEM_INFO structure, to obtain the
system s memory allocation granularity. If there is not enough address space at
the specified address, the function fails.
If lpBaseAddress
is NULL, the operating system chooses the mapping address. In this case, this
function is equivalent to the MapViewOfFile function.
Return Values
If the
function succeeds, the return value is the starting address of the mapped view.
If the
function fails, the return value is NULL. To get extended error information,
call GetLastError.
Remarks
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 is mapped at the specified address
(rounded down to the nearest 64K boundary) if there is enough address space at
the specified address. If there is not, the function fails.
Typically,
the suggested address is used to specify that a file should be mapped at the
same address in multiple processes. This requires the region of address space
to be available in all involved processes. No other memory allocation,
including use of the VirtualAlloc function to reserve memory, can take place in
the region used for mapping.
Windows
95: If the lpBaseAddress
parameter specifies a base offset, the function succeeds only if the same
memory region is available for the memory mapped file in all other 32-bit
processes.
Windows
NT: If the lpBaseAddress
parameter specifies a base offset, the function succeeds if the given memory
region is not already in use by the calling process. the system does not
guarantee that the same memory region is available for the memory mapped file
in other 32-bit processes.
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 specified 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 by using the DuplicateHandle
function, 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 by the ReadFile
or WriteFile function.
See Also