# Function Reference

# _WinAPI_CreateFileMapping

Creates or opens a named or unnamed file mapping object for a specified file

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

## Parameters

$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, _WinAPI_CreateFileMapping() 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.

## Return Value

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 _WinAPI_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.
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 _WinAPI_MapViewOfFile() 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 _WinAPI_UnmapViewOfFile() and close the file mapping object handle by calling _WinAPI_CloseHandle().
These functions can be called in any order.

## Related

_WinAPI_CloseHandle, _WinAPI_UnmapViewOfFile

## See Also

Search CreateFileMapping in MSDN Library.

## Example

    #NoTrayIcon

    #include <MsgBoxConstants.au3>
    #include <StringConstants.au3>
    #include <WinAPIFiles.au3>
    #include <WinAPIHObj.au3>

    Opt('WinWaitDelay', 0)

    Global Const $g_sTitle = '_WinAPI_MapViewOfFile' & ChrW(160)

    If Not $CmdLine[0] Then
        If WinExists($g_sTitle) Then
            Exit
        EndIf
        For $i = 1 To 2
            If Not @Compiled Then
                Run(@AutoItExe & ' "' & @ScriptFullPath & '" /' & $i)
            Else
                Run(@AutoItExe & ' /' & $i)
            EndIf
            Sleep(500)
        Next
        Exit
    EndIf

    Opt('TrayIconHide', 0)

    Switch $CmdLine[1]
        Case '/1'
            _Sender()
        Case '/2'
            _Receiver()
        Case Else
            Exit
    EndSwitch

    Func _Receiver()
        Local $hMapping = _WinAPI_OpenFileMapping('MyFileMapping')
        If Not $hMapping Then Return

        Local $pAddress = _WinAPI_MapViewOfFile($hMapping)
        Local $tData = DllStructCreate('wchar[1024]', $pAddress)
        Local $sText
        While WinWait($g_sTitle, '', 1)
            Sleep(200)
            $sText = DllStructGetData($tData, 1)
            DllStructSetData($tData, 1, '')
            If $sText Then MsgBox(($MB_ICONINFORMATION + $MB_SYSTEMMODAL), $g_sTitle & " (receiver)", "                                               " & @CRLF & $sText)
        WEnd
        _WinAPI_UnmapViewOfFile($pAddress)
        _WinAPI_CloseHandle($hMapping)
    EndFunc   ;==>_Receiver

    Func _Sender()
        Local $hMapping = _WinAPI_CreateFileMapping(-1, 2048, 'MyFileMapping')
        If Not $hMapping Or @extended Then
            MsgBox(($MB_ICONERROR + $MB_SYSTEMMODAL), 'Error', 'Unable to create file mapping (@extended=' & @extended & ').')
            Return
        EndIf

        Local $pAddress = _WinAPI_MapViewOfFile($hMapping)
        Local $tData = DllStructCreate('wchar[1024]', $pAddress)
        Local $sText
        While WinWaitClose($g_sTitle)
            $sText = StringStripWS(InputBox($g_sTitle & " (sender)", 'Type some text message.', '', '', -1, 171), BitOR($STR_STRIPLEADING, $STR_STRIPTRAILING))
            If Not $sText Then
                ExitLoop
            EndIf
            DllStructSetData($tData, 1, $sText)
            If Not WinWait($g_sTitle, '', 1) Then
                ExitLoop
            EndIf
        WEnd
        _WinAPI_UnmapViewOfFile($pAddress)
        _WinAPI_CloseHandle($hMapping)
    EndFunc   ;==>_Sender