###User Defined Function###
_WinAPI_CreateFileMapping

###Description###
Creates or opens a named or unnamed file mapping object for a specified file.

###Syntax###
#include <WinAPIFiles.au3>
_WinAPI_CreateFileMapping ( $hFile [, $iSize = 0 [, $sName = '' [, $iProtect = 0x0004 [, $tSecurity = 0]]]] )


###Parameters###
@@ParamTable@@
$hFile
	Handle to the file from which to create a file mapping object.
	If this parameter is (-1), the calling process must also specify a size for the file mapping object in the $iSize parameters.
	In this scenario, <a href="_WinAPI_CreateFileMapping.htm">_WinAPI_CreateFileMapping()</a> 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.
$iSize
	[optional] The maximum size of the file mapping object.
	If this parameter is 0 (Default), the maximum size of the file mapping object is equal to the current size of the file that $hFile identifies.
$sName
	[optional] The name of the file mapping object.
$iProtect
	[optional] Specifies the page protection of the file mapping object and can be one of the following values.
		$PAGE_EXECUTE_READ
		$PAGE_EXECUTE_READWRITE
		$PAGE_EXECUTE_WRITECOPY
		$PAGE_READONLY
		$PAGE_READWRITE (Default)
		$PAGE_WRITECOPY

	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.
		$SEC_COMMIT
		$SEC_IMAGE
		$SEC_LARGE_PAGES
		$SEC_NOCACHE
		$SEC_RESERVE
		$SEC_WRITECOMBINE
$tSecurity
	[optional] $tagSECURITY_ATTRIBUTES structure that determines whether a returned handle can be inherited by child processes.
	If this parameter is 0 (Default), the handle cannot be inherited and the file mapping object gets a default security descriptor.
@@End@@

###ReturnValue###
@@ReturnTable@@
Success 	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 sets the @extended flag to $ERROR_ALREADY_EXISTS (183).
Failure 	0, @extended flag is set to  <a href="_WinAPI_GetLastError.htm">_WinAPI_GetLastError()</a>.
@@End@@


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

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.

A file mapping object does not actually map the view into a process address space. The <a href="_WinAPI_MapViewOfFile.htm">_WinAPI_MapViewOfFile()</a> functions map a view of a file into a process address space.

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 <a href="_WinAPI_UnmapViewOfFile.htm">_WinAPI_UnmapViewOfFile()</a> and close the file mapping object handle by calling <a href="_WinAPI_CloseHandle.htm">_WinAPI_CloseHandle()</a>.
These functions can be called in any order.


###Related###
_WinAPI_UnmapViewOfFile, _WinAPI_CloseHandle


###See Also###
@@MsdnLink@@ CreateFileMapping


###Example###
@@IncludeExample@@
