CreateFileMapping (Compact 2013)

3/26/2014

This function creates a named or unnamed file-mapping object for the specified file.

Syntax

HANDLE CreateFileMapping(
  HANDLE hFile,
  LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
  DWORD flProtect,
  DWORD dwMaximumSizeHigh,
  DWORD dwMaximumSizeLow,
  LPCTSTR lpName 
);

Parameters

• hFile
  [in] Handle to the file from which to create a mapping object. The file must be opened with an access mode compatible with the protection flags specified by the flProtect parameter. Open files that you intend to map for exclusive access. If two handles to the file are open at the same time, inconsistencies between the file and the mapped view of it can occur. Use only FILE_SHARE_READ or FILE_SHARE_WRITE when you call the CreateFile function if you are prepared to synchronize between the two handles.

  If this parameter is set to (HANDLE)INVALID_HANDLE_VALUE, the calling process must also specify a mapping object size in the dwMaximumSizeHigh and the dwMaximumSizeLow parameters. The function creates a file-mapping object of the specified size, backed by physical memory, rather than by a named file in the file system. The file-mapping object can be shared by name. In Windows Embedded Compact, memory used for the mapping object is not part of the 32 MB virtual process space.

  The value of this parameter can come from the CreateFile function. However, the file handle differs between this function and the CloseHandle function.

• lpFileMappingAttributes
  [in] Ignored. Must be set to NULL.

• flProtect
  [in] Protection for the file view, when the file is mapped. The following table shows possible values.

  Value	Description
  PAGE_READONLY	Gives read-only access to the committed region of pages. An attempt to write to or execute the committed region results in an access violation. The file specified by hFile must have been created with GENERIC_READ access. You cannot specify PAGE_READONLY without a file handle.
  PAGE_READWRITE	Gives read-write access to the committed region of pages. The file specified by hFile must have been created with GENERIC_READ and GENERIC_WRITE access.
  PAGE_WRITECOPY	Not supported.

  In addition, an application can specify certain section attributes by combining one or more section attribute values with one of the preceding page protection values, using the bitwise OR operator. The following table shows possible section attribute values.

  Value	Description
  SEC_COMMIT	Allocates physical storage in memory or in the paging file on disk for all pages of a section. This is the default setting.
  SEC_IMAGE	Not supported.
  SEC_NOCACHE	Not supported.
  SEC_RESERVE	Not supported.

• dwMaximumSizeHigh
  [in] Specifies the high order 32 bits of the maximum size of the file-mapping object.

  If you intend to grow the file, specify the maximum file size so that the kernel can reserve the correct amount of memory.

• dwMaximumSizeLow
  [in] Specifies the low order 32 bits of the maximum size of the file-mapping object. If this parameter and dwMaximumSizeHighare set to zero, the maximum size of the file-mapping object is equal to the current size of the file specified by hFile.

  If dwMaximumSizeLowis set to zero, the function returns an error that indicates an invalid parameter.

• lpName
  [in] Long pointer to a null-terminated string specifying the name of the mapping object. The name can contain any character.

  If this parameter matches the name of an existing named mapping object, the function requests access to the mapping object with the protection specified by flProtect.

  Each object type, such as memory maps, semaphores, events, message queues, mutexes, and watchdog timers, has its own separate namespace. Empty strings ("") are handled as named objects. On Windows desktop-based platforms, synchronization objects all share the same namespace.

Return Value

Returns a handle to the file-mapping object if the function is successful; otherwise, returns NULL. To retrieve extended error information, call GetLastError.

If the object existed before the function call, the function returns a handle to the existing object with its current size, not the specified size, and GetLastError returns ERROR_ALREADY_EXISTS.

If dwMaximumSizeLowis set to zero, GetLastError returns ERROR_INVALID_PARAMETER.

Remarks

Because of memory resource constraints, this function does not create mapfiles mapped directly to ROM, or mapfiles that don't use the paging pool and that are larger than 4 GB. The MapViewOfFile function can create views if the current process has enough virtual address space to contain them.

A memory-mapped file should not be accessed by using the ReadFile or the WriteFile function. This can result in inconsistencies between the file and the memory-mapped file.

Two writable handles to the same file cannot be open at the same time to prevent inconsistencies between the file and the mapped view of it. For two processes to share the data in a memory-mapped file, they must both memory-map the file.

This function requires support for demand paging, which lets different processes share memory. For more information, see DISK_INFO.

After a file-mapping object has been created, the size of the file must not exceed the size of the file-mapping object. If it does, not all file contents are available for sharing.

If an application specifies a size for the file-mapping object that is larger than the size of the named file, the file size is increased to match the specified size of the file-mapping object. If the file size cannot be increased, the file-mapping object is not created. GetLastError returns ERROR_DISK_FULL.

The handle that this function returns has full access to the new file-mapping object. It can be used with any function that requires a handle to a file-mapping object. File-mapping objects can be shared through process creation.

File handles that have been used to create file-mapping objects must not be used in subsequent calls to file I/O functions, such as ReadFile and WriteFile. Generally, if a file handle has been used in a successful call to this function, only use that handle after closing the corresponding file-mapping object.

By creating a file-mapping object you can map a view of the file. To map the view of the file into the address space of a process, call MapViewOfFile.

Most file views derived from a single file-mapping object are identical at a specified time. If multiple processes have handles of the same file-mapping object, they see a coherent view of the data when they map a view of the file. File views for remote files cannot be identical. For example, if two computers both map a file as writable, and both change the same page, each computer sees only its own view as it writes to the page. When the data is updated on the disk, it is not merged.

To close a file-mapping object, an application must unmap all mapped views of the file-mapping object by calling the UnmapViewOfFile function, and close the file-mapping object handle by calling CloseHandle. You can call these functions in any order. You don’t have to call UnmapViewOfFile because mapped views of a file-mapping object maintain internal open handles to the object, and a file-mapping object does not close until all open handles to it are closed.

If the file being mapped is an uncompressed ROM file and it is mapped with PAGE_READONLY access, the file is accessed directly from ROM without using any RAM to cache the data.

The following example code uses the CreateFileMapping function.

hMap = CreateFileMapping(...);

if (hMap != NULL && GetLastError() == ERROR_ALREADY_EXISTS)
{
   CloseHandle(hMap);
   hMap = NULL;
}

return hMap;

Requirements

See Also

Reference

File Mapping Functions
CloseHandle
MapViewOfFile
ReadFile
UnmapViewOfFile
WriteFile

Other Resources

VirtualAlloc