# Function Reference

# _WinAPI_CreateFile

Creates or opens a file or other device

#include <WinAPIFiles.au3>
_WinAPI_CreateFile ( $sFileName, $iCreation [, $iAccess = 4 [, $iShare = 0 [, $iAttributes = 0 [, $tSecurity = 0]]]] )

## Parameters

$sFileName | Name of an object to create or open
$iCreation | Action to take on files that exist and do not exist: 0 - Creates a new file. The function fails if the file exists 1 - Creates a new file. If a file exists, it is overwritten 2 - Opens a file. The function fails if the file does not exist 3 - Opens a file. If the file does not exist, the function creates the file 4 - Opens a file and truncates it so that its size is 0 bytes. The function fails if the file does not exist.
$iAccess | [optional] Access to the object: 1 - Execute 2 - Read 4 - Write
$iShare | [optional] Sharing mode of an object: 1 - Delete 2 - Read 4 - Write
$iAttributes | [optional] The file attributes: 1 - File should be archived 2 - File is hidden 4 - File is read only 8 - File is part of or used exclusively by an operating system.
$tSecurity | [optional] a $tagSECURITY_ATTRIBUTES structure or a pointer to it that determines if the returned handle can be inherited by child processes. If $tSecurity is 0, the handle cannot be inherited.

## Return Value

Success: | The open handle to a specified file
Failure: | 0, call _WinAPI_GetLastError() to get extended error information

## Related

$tagSECURITY_ATTRIBUTES, _WinAPI_CloseHandle, _WinAPI_FlushFileBuffers, _WinAPI_GetFileSizeEx, _WinAPI_ReadFile, _WinAPI_SetEndOfFile, _WinAPI_SetFilePointer, _WinAPI_WriteFile

## See Also

Search CreateFile in MSDN Library.

## Example

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

    Local $sTempFile, $hFile, $sText, $nBytes, $tBuffer, $iSize

    ; 1) create file and write data to it
    $sTempFile = @TempDir & '\test.txt'
    $sText = 'abcdefghijklmnopqrstuvwxyz'
    $tBuffer = DllStructCreate("byte[" & StringLen($sText) & "]")
    DllStructSetData($tBuffer, 1, $sText)
    $hFile = _WinAPI_CreateFile($sTempFile, 1)
    _WinAPI_WriteFile($hFile, $tBuffer, StringLen($sText), $nBytes)
    $iSize = _WinAPI_GetFileSizeEx($hFile)
    _WinAPI_CloseHandle($hFile)
    ConsoleWrite('1):' & $iSize & ' ' & FileRead($sTempFile) & @CRLF)

    ; 2) read 6 bytes from position 3
    $tBuffer = DllStructCreate("byte[6]")
    $hFile = _WinAPI_CreateFile($sTempFile, 2, 2)
    $iSize = _WinAPI_GetFileSizeEx($hFile)
    _WinAPI_SetFilePointer($hFile, 3)
    _WinAPI_ReadFile($hFile, $tBuffer, 6, $nBytes)
    _WinAPI_CloseHandle($hFile)
    $sText = BinaryToString(DllStructGetData($tBuffer, 1))
    ConsoleWrite('2):' & $iSize & ' ' & $sText & @CRLF)

    ; 3) write previously read 6 bytes from position 3 to the same position but in UpperCase
    DllStructSetData($tBuffer, 1, StringUpper($sText))
    $hFile = _WinAPI_CreateFile($sTempFile, 2, 4)
    $iSize = _WinAPI_GetFileSizeEx($hFile)
    _WinAPI_SetFilePointer($hFile, 3)
    _WinAPI_WriteFile($hFile, $tBuffer, 6, $nBytes)
    _WinAPI_CloseHandle($hFile)
    $tBuffer = 0
    ConsoleWrite('3):' & $iSize & ' ' & FileRead($sTempFile) & @CRLF)

    ; 4) truncate file size to 12 bytes
    $hFile = _WinAPI_CreateFile($sTempFile, 2, 4)
    _WinAPI_SetFilePointer($hFile, 12)
    _WinAPI_SetEndOfFile($hFile)
    $iSize = _WinAPI_GetFileSizeEx($hFile)
    _WinAPI_CloseHandle($hFile)
    ConsoleWrite('4):' & $iSize & ' ' & FileRead($sTempFile) & @CRLF)

    FileDelete($sTempFile)