Funktionsreferenz

DllCall

Ruft eine Funktion in einer DLL dynamisch auf.

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

 

Parameter

dll Der Dateiname der zu verwendenden DLL, z.B. "user32.dll". Es kann auch ein Handle verwendet werden, das von DllOpen zurückgegeben wird (siehe Bemerkungen).
return type Der Rückgabewert der Funktion (siehe unten).
function Der Name oder die Nummer der Funktion in der DLL, die aufgerufen werden soll, z.B. "MessageBox" oder 62.
type1 [optional] Der Typ des Parameters (siehe Bemerkungen).
param1 [optional] Der eigentliche Parameter (siehe Bemerkungen).
type n [optional] Der Typ des n. Parameters (siehe Bemerkungen).
param n [optional] Der eigentliche n. Parameter (siehe Bemerkungen).
Gültige Typen sind:
Typ Details
none ohne Wert (nur als Rückgabewert zulässig - entspricht dem void in C)
BYTE vorzeichenloser 8 bit Integerwert
BOOLEAN vorzeichenloser 8 bit Integerwert
short 16 bit Integerwert
USHORT vorzeichenloser 16 bit Integerwert
WORD vorzeichenloser 16 bit Integerwert
int 32 bit Integerwert
long 32 bit Integerwert
BOOL 32 bit Integerwert
UINT vorzeichenloser 32 bit Integerwert
ULONG vorzeichenloser 32 bit Integerwert
DWORD vorzeichenloser 32 bit Integerwert
INT64 64 bit Integerwert
UINT64 vorzeichenloser 64 bit Integerwert
ptr allgemeiner Zeiger (pointer), (void *)
HWND Fensterhandle (Zeiger)
float Gleitkommazahl, einfache Genauigkeit
double Gleitkommazahl, doppelte Genauigkeit
INT_PTR, LONG_PTR, LRESULT, LPARAM Integerwert, der groß genug ist, einen Zeiger aufzunehmen, abhängig von der AutoIt-Version (x86 oder x64)
UINT_PTR, LONG_PTR, LRESULT, LPARAM vorzeichenloser Integerwert, der groß genug ist, einen Zeiger aufzunehmen, abhängig von der AutoIt-Version (x86 oder x64)
str ANSI-String (maximal 65536 Zeichen)
wstr UNICODE-Wide-String (Umwandlung von/nach ANSI-String während des Aufrufs, wenn notwendig), maximal 65536 Zeichen
* Hänge * an das Ende eines anderen Typs an, um ihn als Referenz zu übergeben. Zum Beispiel übergibt "int*" einen Zeiger auf einen "int"-Typ.
Vergleich der Windows-API-Typen mit den AutoIt-Typen:
WINDOWS-API-Typ AutoIt-Typ
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
Um verschachtelte Strukturen innerhalb einer Struktur zu verwenden muss die verschachtelte Struktur neu definiert werden.
So würde zum Beispiel eine Struktur die eine 2 POINT Struktur enthält ("long;long") als "long;long;long;long" deklariert. Die ersten long Werte entsprechen der ersten POINT Struktur und die zweiten Werte entsprechen der zweiten POINT Struktur.
Für mehr Windows API Typen siehe MSDN.

 

Rückgabewert

Erfolg: @error = 0.
Fehler: setzt @error
@error: 1 Die Dll-Datei kann nicht verwendet werden,
2 unbekannter Rückgabewert "return type",
3 Funktion "function" wurde in der DLL-Datei nicht gefunden.
4 Falsche Anzahl von Parametern.
siehe Bemerkungen.

 

Bemerkungen

Wenn der Dateiname einer DLL angegeben wird, wird die DLL automatisch geladen und nach den Funktionsaufruf wieder geschlossen. Wenn man das Laden und Entladen selbst kontrollieren will, verwendet man dazu die Funktionen DllOpen und DllClose und gibt statt des Dateinamens ein Handle an.

Normalerweise benutzt AutoIt die 'stdcall'-Befehlsmethode. Um die 'cdecl'-Methode zu benutzen ist ':cdecl' nach dem Rückgabewert "return type" zu setzen:
DllCall("SQLite.dll", "int:cdecl", "sqlite3_open", "str", $sDatabase_Filename , "long_*", 0).

Standardmäßig versucht AutoIt, die ANSI-Variante des Funktionsnamens zu verwenden, d.h. MessageBoxA wird verwendet, wenn MessageBox als Funktionsname gegeben ist. Um explizit die Unicode-Variante aufzurufen, kann MessageBoxW verwendet werden.

Wenn der Funktionsaufruf scheitert, wird @error auf 1 gesetzt. Ansonsten wird ein Array mit dem Rückgabewert der Funktion und einer Kopie aller Parameter (inklusive derer, die die Funktion möglicherweise verändert hat) zurückgegeben.
$return[0] = Rückgabewert der Funktion
$return[1] = Param1
$return[2] = Param2
...
$return[n] = Paramn

Es können beliebig viele "type"- und "param"-Parameter angegeben werden. Siehe die Beispiele unten, die viele Parameter verwenden.

 

Verwandte Funktionen

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

 

Beispiel


; *******************************************************
; Beispiel 1 - direkter Aufruf der MessageBox API
; *******************************************************

$result = DllCall("user32.dll", "int", "MessageBox", "hwnd", 0, "str", "Irgendein Text", "str", "Ein Titel", "int", 0)


; *******************************************************
; Beispiel 2 - Aufrufen einer Funktion, die Parameter verändert
; *******************************************************
$PID=Run('Notepad.exe')
WinWaitActive("[CLASS:Notepad]",'',5)
$hwnd = WinGetHandle("[CLASS:Notepad]")
$result = DllCall("user32.dll", "int", "GetWindowText", "hwnd", $hwnd, "str", "", "int", 32768)
MsgBox(0, "Notepad-Info: Länge des Titels", $result[0]) ; Anzahl der zurückgegebenen Zeichen
MsgBox(0, "Notepad-Info: Fenstertitel", $result[2]) ; Zurückgegebener Text in Parameter 2
ProcessClose($PID)


; *******************************************************
; Beispiel 3 - Den Windows PickIconDlg anzeigen
; *******************************************************
$sFileName = @SystemDir & '\shell32.dll'

; Struktur erzeugen um den Iconindex abzuspeichern
$stIcon = DllStructCreate("int")
$stString = DllStructCreate("wchar[260]")
$structsize = DllStructGetSize($stString) / 2
DllStructSetData($stString, 1, $sFileName)

; Den PickIconDlg starten - '62' ist der Ordinalwert für diese Funktion
DllCall("shell32.dll", "none", 62, "hwnd", 0, "ptr", DllStructGetPtr($stString), "int", $structsize, "ptr", DllStructGetPtr($stIcon))

$sFileName = DllStructGetData($stString, 1)
$nIconIndex = DllStructGetData($stIcon, 1)

; Den neuen Dateinamen und den Iconindex anzeigen
MsgBox(0, "Icon-Info", "Die zuletzt ausgewählte Datei: " & @LF&@LF & $sFileName & @LF & "Icon-Index: " & $nIconIndex)