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 = 0x0004 [, $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 <WinAPI.au3>
#include <WinAPIFiles.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(BitOR($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(BitOR($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), 3)
        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