# Function Reference

# DllCall

Dynamically calls a function in a DLL.

DllCall ( "dll", "return type", "function" [, type1, param1 [, type n, param n]] )

## Parameters

dll | The filename of the DLL to use. e.g. "user32.dll". A handle obtained from DllOpen can also be used (See Remarks).
return type | The return type of the function (see below).
function | The name, eg. "MessageBox" or the ordinal value, e.g. 62, of the function in the DLL to call.
type1 | [optional] The type of the parameter (see remarks).
param1 | [optional] The actual parameter (see remarks).
type n | [optional] The type of the nth parameter (see remarks).
param n | [optional] The actual nth parameter (see remarks).

Valid Types are:

Type | Details
NONE | no value (only valid for return type - equivalent to void in C)
BYTE | an unsigned 8 bit integer
BOOLEAN | an unsigned 8 bit integer
SHORT | a 16 bit integer
USHORT | an unsigned 16 bit integer
WORD | an unsigned 16 bit integer
INT | a 32 bit integer
LONG | a 32 bit integer
BOOL | a 32 bit integer
UINT | an unsigned 32 bit integer
ULONG | an unsigned 32 bit integer
DWORD | an unsigned 32 bit integer
INT64 | a 64 bit integer
UINT64 | an unsigned 64 bit integer
PTR | a general pointer (void *)
HWND | a window handle (pointer)
HANDLE | an handle (pointer)
FLOAT | a single precision floating point number
DOUBLE | a double precision floating point number
INT_PTR, LONG_PTR, LRESULT, LPARAM | an integer big enough to hold a pointer when running on x86 or x64 versions of AutoIt.
UINT_PTR, ULONG_PTR, DWORD_PTR, WPARAM | an unsigned integer big enough to hold a pointer when running on x86 or x64 versions of AutoIt.
STR | an ANSI string (a minimum of 65536 chars is allocated).
WSTR | a UNICODE wide character string (a minimum of 65536 chars is allocated).
STRUCT | structure created with DllStructCreate()
* | Add * to the end of another type to pass it by reference. For example "int*" passes a pointer to an "int" type.

Conversions from Windows API types to AutoIt types:

WINDOWS API Type | AutoIt Type
LPCSTR/LPSTR | STR
LPCWSTR/LPWSTR | WSTR
LPVOID | PTR
LPxyz | xyz*
HINSTANCE | HANDLE
HRESULT | LONG
LONGLONG/LARGE_INTEGER | INT64
ULONGLONG/ULARGE_INTEGER | UINT64
SIZE_T | ULONG_PTR

To use nested structures inside a structure you must re-define the nested structure. For example, a structure containing 2 POINT structures ("long;long") would be declared as "long;long;long;long". The first two long values correspond to the first POINT structure and the second two values correspond to the second POINT structure.
For more Windows API types see MSDN.

## Return Value

Success: | an array. See remarks.
Failure: | sets the @error flag to non-zero.
@error: | 1 = unable to use the DLL file, 2 = unknown "return type", 3 = "function" not found in the DLL file, 4 = bad number of parameters, 5 = bad parameter.

## Remarks

If a dll filename is given then the DLL is automatically loaded and then closed at the end of the call. If you want to manually control the loading and unloading of the DLL then you should use DllOpen() and DllClose() and use a handle instead of a filename in this function.
By default, AutoIt uses the 'stdcall' calling method. To use the 'cdecl' method place ':cdecl' after the return type.
DllCall("SQLite.dll", "int:cdecl", "sqlite3_open", "str", $sDatabase_Filename , "long*", 0).
By default, AutoIt tries to use the ANSI version of a function name, i.e. MessageBoxA is attempted when MessageBox is given as the function name. To call the unicode version use MessageBoxW.
If the function call fails then @error is set to non-zero.
Otherwise an array is returned that contains the function return value and a copy of all the parameters (including parameters that the function may have modified when passed by reference).
$return[0] = function return value
$return[1] = param1
$return[2] = param2
...
$return[n] = paramn
If an output parameter with type STR or WSTR is defined as a Null string only a maximum 65536 string will be return.

## Related

DllCallbackFree, DllCallbackGetPtr, DllCallbackRegister, DllClose, DllOpen, DllStructCreate, DllStructGetPtr

## Example

### Example 1

    ; Calling the MessageBox API directly.
    DllCall("user32.dll", "int", "MessageBox", _
            "hwnd", 0, _ ; Handle to the parent window
            "str", "Some text", _ ; The text of the message box
            "str", "Some title", _ ; The title of the message box
            "int", 0) ; Flags for the message box.

### Example 2

    #include <MsgBoxConstants.au3>

    ; Calling a function that modifies parameters,
    Local $iPID = Run("notepad")

    Local $hWnd = WinWaitActive("[CLASS:Notepad]", "")

    If $hWnd = 0 Then
        ; Timeout occured.
        Exit MsgBox($MB_SYSTEMMODAL, Default, "Unable to start notepad!")
    EndIf

    Local $aResult = DllCall("user32.dll", "int", "GetWindowText", "hwnd", $hWnd, "str", "", "int", 32768)
    MsgBox($MB_SYSTEMMODAL, Default, "Number of characters returned: " & $aResult[0])
    MsgBox($MB_SYSTEMMODAL, Default, "Text (returned in parameter 2): '" & $aResult[2] & "'")

    WinClose($hWnd)

### Example 3

    #include <MsgBoxConstants.au3>

    ; Show the Windows PickIconDlg.
    Local $sFileName = @SystemDir & '\shell32.dll'

    ; Create a structure to store the icon index
    Local $tIconIndex = DllStructCreate("int")
    Local $tString = DllStructCreate("wchar[260]")
    Local $iStructsize = DllStructGetSize($tString) / 2
    DllStructSetData($tString, 1, $sFileName)

    ; Run the PickIconDlg - '62' is the ordinal value for this function
    DllCall("shell32.dll", "none", 62, _
            "hwnd", 0, _
            "struct*", $tString, _
            "int", $iStructsize, _
            "struct*", $tIconIndex)

    $sFileName = DllStructGetData($tString, 1)
    Local $iIconIndex = DllStructGetData($tIconIndex, 1)

    ; Show the new filename and icon index
    MsgBox($MB_SYSTEMMODAL, "Info", "Last selected file: " & $sFileName & @CRLF & "Icon-Index: " & $iIconIndex)