Mapping a Memory Object to a File (Windows Embedded CE 6.0)

  • Article

1/6/2010

Memory mapping allows access to a file though a memory object that is mapped directly to the file. Memory-mapped files also provide a way to conduct interprocess communication.

While memory mapping is somewhat more complicated to set up than traditional memory access, it simplifies file access by eliminating the need for a system-maintained pointer for read and write operations. Changes are written directly to memory and Windows Embedded CE reflects any change to the memory-mapped object back to the file.

When you call the CreateFileMapping function, you specify an object name, the number of bytes to be mapped from the file, and the read/write permission for the mapped memory. The first process that calls CreateFileMapping creates the file mapping object. Processes calling CreateFileMapping with the same object name receive a handle to the existing object.

You can tell whether or not a successful call to CreateFileMapping created or opened the file mapping object by calling the GetLastError function. GetLastError returns NO_ERROR to the creating process and ERROR_ALREADY_EXISTS to subsequent processes.

To set up and access a file using memory mapping

  1. Call the CreateFileForMapping function to open or create the memory-mapped file. If a single file is to be shared between applications, only one application should call CreateFile.

  2. Use the CreateFileMapping function to create an object in memory and to tie the object to the file that is opened by CreateFile.

  3. Use the MapViewOfFile function to create a view of the memory-mapped object.

  4. Use the pointer that is returned by MapViewOfFile to gain direct access to the memory-mapped object.

  5. Call the UnmapViewOfFile function to unmap the object view.

  6. Call CloseHandle to close the memory object.

  7. Call CloseHandle to close the file.

Security for Memory-Mapped Files

To ensure that other processes cannot write to the portion of the file that is mapped, open the file with exclusive access. In addition, the file handle should remain open until the process no longer needs the file-mapping object.

An easy way to obtain exclusive access is to specify zero in the dwShareMode parameter of the CreateFile function or the CreateFileForMapping function.

CreateFileMapping fails if the access flags conflict with those specified when CreateFile opened the file. For example, to read and write to the file:

  1. Specify the GENERIC_READ and GENERIC_WRITE values in the dwAccess parameter of CreateFile.
  2. Specify the PAGE_READWRITE value in the flProtect parameter of CreateFileMapping.

File Mapping Size

The size of the file mapping object is not independent of the size of the file being mapped. If the file mapping object is larger than the file, the system expands the file before CreateFileMapping returns. If you specify that the file mapping object should be smaller than the file, the system maps the entire file.

The dwMaximumSizeHigh and dwMaximumSizeLow parameters of CreateFileMapping enable you to specify the number of bytes to be mapped from the file, as follows:

  • When you do not want the size of the file to change (for example, when mapping read-only files), call CreateFileMapping, and specify zero for both dwMaximumSizeHigh and dwMaximumSizeLow. Doing this creates a file-mapping object the same size as the file. Otherwise, you must calculate or estimate the size of the finished file because file mapping objects are static in size. An attempt to map a read-only file with a length of zero fails with an error code of ERROR_ INVALID_PARAMETER. Applications should test for files with a length of zero and reject such files.
  • The size of a file-mapping object backed by a file is limited by disk space. The size of a file view is limited to the largest available contiguous block of unreserved virtual memory. This is at most 2 GB, minus the virtual memory already reserved by the process.

If you want to view a portion of the file that does not start at the beginning of the file, you must create a file-mapping object. This object is the size of the portion of the file that you want to view, plus the offset into the file.

See Also

Reference

CreateFile
CreateFileForMapping
CreateFileMapping
MapViewOfFile
UnmapViewOfFile

Other Resources

Memory Mapping a File
Memory-mapped Files