# 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.
type | [optional] The type of the parameter (see remarks).
param | [optional] The actual parameter (see remarks).

Return Value

Success: | @error = 0.
Failure: | @error = 1 unable to use the DLL file,
| @error = 2 unknown "return type",
| @error = 3 "function" not found in the DLL file.

See remarks.

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_ptr", 0).
You can have as many "types" and "param" as you like. See the examples below that use a number of parameters.
Valid Types are:

Type | Details
none | no value (only valid for return type - equivalent to void in C)
short | a 16 bit integer
int | a 32 bit integer
long | a 32 bit integer
short_ptr | a pointer to a 16 bit integer
int_ptr | a pointer to a 32 bit integer
long_ptr | a pointer to a 32 bit integer
str | a string
wstr | a wide character string (converted to/from an ANSI string during the call)
hwnd | a window handle
ptr | a general pointer (void *)

If the function call fails then @error is set to 1. 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).
$return[0] = function return value
$return[1] = param1
$return[2] = param2
...
$return[n] = paramn

Related

DLLOpen, DllClose

Example

; *******************************************************
; Example 1 - calling the MessageBox API directly
; *******************************************************
$result = DllCall("user32.dll", "int", "MessageBox", "hwnd", 0, "str", "Some text", "str", "Some title", "int", 0)
; *******************************************************
; Example 2 - calling a function that modifies parameters
; *******************************************************
$hwnd = WinGetHandle("Untitled - Notepad")
$result = DllCall("user32.dll", "int", "GetWindowText", "hwnd", $hwnd, "str", "", "int", 32768)
msgbox(0, "", $result[0]) ; number of chars returned
msgbox(0, "", $result[2]) ; Text returned in param 2
; *******************************************************
; Example 3 - Show the Windows PickIconDlg
; *******************************************************
$sFileName = @SystemDir & '\shell32.dll'
; Create a strcuture to store the icon index
$stIcon = DllStructCreate("int")
If @OSType = "WIN32_NT" Then
; Convert and store the filename as a wide char string
$nBuffersize = DllCall("kernel32.dll", "int", "MultiByteToWideChar", "int", 0, "int", 0x00000001, "str", $sFileName, "int", -1, "ptr", 0, "int", 0)
$stString = DLLStructCreate("byte[" & 2 * $nBuffersize[0] & "]")
DllCall("kernel32.dll", "int", "MultiByteToWideChar", "int", 0, "int", 0x00000001, "str", $sFileName, "int", -1, "ptr", DllStructGetPtr($stString), "int", $nBuffersize[0])
Else
; Win'9x
$stString = DLLStructCreate("char[260]")
DllStructSetData($stString, 1, $sFileName)
EndIf
; Run the PickIconDlg - '62' is the ordinal value for this function
DllCall("shell32.dll", "none", 62, "hwnd", 0, "ptr", DllStructGetPtr($stString), "int", DllStructGetSize($stString), "ptr", DllStructGetPtr($stIcon))
If @OSType = "WIN32_NT" Then
; Convert the new selected filename back from a wide char string
$nBuffersize = DllCall("kernel32.dll", "int", "WideCharToMultiByte", "int", 0, "int", 0x00000200, "ptr", DllStructGetPtr($stString), "int", -1, "ptr", 0, "int", 0, "ptr", 0, "ptr", 0)
$stFile = DLLStructCreate("char[" & $nBuffersize[0] & "]")
DllCall("kernel32.dll", "int", "WideCharToMultiByte", "int", 0, "int", 0x00000200, "ptr", DllStructGetPtr($stString), "int", -1, "ptr", DllStructGetPtr($stFile), "int", $nBuffersize[0], "ptr", 0, "ptr", 0)
$sFileName = DllStructGetData($stFile, 1)
Else
$sFileName = DllStructGetData($stString, 1)
EndIf
$nIconIndex = DllStructGetData($stIcon, 1)
; Show the new filename and icon index
Msgbox(0, "Info", "Last selected file: " & $sFileName & @LF & "Icon-Index: " & $nIconIndex)
$stBuffer = 0
$stFile = 0
$stIcon = 0