CreateFileMappingFromApp function (memoryapi.h)

Creates or opens a named or unnamed file mapping object for a specified file from a Windows Store app.

Syntax

HANDLE CreateFileMappingFromApp(
  [in]           HANDLE               hFile,
  [in, optional] PSECURITY_ATTRIBUTES SecurityAttributes,
  [in]           ULONG                PageProtection,
  [in]           ULONG64              MaximumSize,
  [in, optional] PCWSTR               Name
);

Parameters

[in] hFile

A handle to the file from which to create a file mapping object.

The file must be opened with access rights that are compatible with the protection flags that the flProtect parameter specifies. It is not required, but it is recommended that files you intend to map be opened for exclusive access. For more information, see File Security and Access Rights.

If hFile is INVALID_HANDLE_VALUE, the calling process must also specify a size for the file mapping object in the dwMaximumSizeHigh and dwMaximumSizeLow parameters. In this scenario, CreateFileMappingFromApp creates a file mapping object of a specified size that is backed by the system paging file instead of by a file in the file system.

[in, optional] SecurityAttributes

A pointer to a SECURITY_ATTRIBUTES structure that determines whether a returned handle can be inherited by child processes. The lpSecurityDescriptor member of the SECURITY_ATTRIBUTES structure specifies a security descriptor for a new file mapping object.

If SecurityAttributes is NULL, the handle cannot be inherited and the file mapping object gets a default security descriptor. The access control lists (ACL) in the default security descriptor for a file mapping object come from the primary or impersonation token of the creator. For more information, see File Mapping Security and Access Rights.

[in] PageProtection

Specifies the page protection of the file mapping object. All mapped views of the object must be compatible with this protection.

This parameter can be one of the following values.

An application can specify one or more of the following attributes for the file mapping object by combining them with one of the preceding page protection values.

[in] MaximumSize

The maximum size of the file mapping object.

An attempt to map a file with a length of 0 (zero) fails with an error code of ERROR_FILE_INVALID. Applications should test for files with a length of 0 (zero) and reject those files.

[in, optional] Name

The name of the file mapping object.

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

If this parameter is NULL, the file mapping object is created without a name.

If lpName matches the name of an existing event, semaphore, mutex, waitable timer, or job object, the function fails, and the GetLastError function returns ERROR_INVALID_HANDLE. This occurs because these objects share the same namespace.

The name can have a "Global" or "Local" prefix to explicitly create the object in the global or session namespace. The remainder of the name can contain any character except the backslash character (\). Creating a file mapping object in the global namespace from a session other than session zero requires the SeCreateGlobalPrivilege privilege. For more information, see Kernel Object Namespaces.

Fast user switching is implemented by using Terminal Services sessions. The first user to log on uses session 0 (zero), the next user to log on uses session 1 (one), and so on. Kernel object names must follow the guidelines that are outlined for Terminal Services so that applications can support multiple users.

Return value

If the function succeeds, the return value is a handle to the newly created file mapping object.

If the object exists 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 the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

After a file mapping object is created, the size of the file must not exceed the size of the file mapping object; if it does, not all of the 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 actual named file on disk and if the page protection allows write access (that is, the flProtect parameter specifies PAGE_READWRITE), then the file on disk is increased to match the specified size of the file mapping object. If the file is extended, the contents of the file between the old end of the file and the new end of the file are not guaranteed to be zero; the behavior is defined by the file system. If the file on disk cannot be increased, CreateFileMappingFromApp fails and GetLastError returns ERROR_DISK_FULL.

The initial contents of the pages in a file mapping object backed by the operating system paging file are 0 (zero).

The handle that CreateFileMappingFromApp returns has full access to a new file mapping object, and can be used with any function that requires a handle to a file mapping object.

Multiple processes can share a view of the same file by either using a single shared file mapping object or creating separate file mapping objects backed by the same file. A single file mapping object can be shared by multiple processes through inheriting the handle at process creation, duplicating the handle, or opening the file mapping object by name. For more information, see the CreateProcess, DuplicateHandle and OpenFileMapping functions.

Creating a file mapping object does not actually map the view into a process address space. The MapViewOfFileEx function map a view of a file into a process address space.

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 CreateFileMappingFromApp 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.

A mapped file and a file that is accessed by using the input and output (I/O) functions (ReadFile and WriteFile) are not necessarily coherent.

Mapped views of a file mapping object maintain internal references to the object, and a file mapping object does not close until all references to it are released. Therefore, to fully close a file mapping object, an application must unmap all mapped views of the file mapping object by calling UnmapViewOfFile and close the file mapping object handle by calling CloseHandle. These functions can be called in any order.

When modifying a file through a mapped view, the last modification timestamp may not be updated automatically. If required, the caller should use SetFileTime to set the timestamp.

Use structured exception handling to protect any code that writes to or reads from a file view. For more information, see Reading and Writing From a File View.

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

Requirements

See also

CloseHandle

CreateFileMapping

Creating a File Mapping Object

DuplicateHandle

File Mapping Functions

MapViewOfFile

MapViewOfFileEx

Memory Management Functions

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAlloc

WriteFile