Funktionsreferenz
DllCall
Ruft eine Funktion in einer DLL dynamisch auf.
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 |
| struct |
Struktur erstellt durch DllStructCreate() |
| * |
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. |
|
5 Falscher Parameter. |
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
; *******************************************************
Local $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
; *******************************************************
Local $PID = Run('Notepad.exe')
WinWaitActive("[CLASS:Notepad]", '', 5)
Local $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
; *******************************************************
Local $sFileName = @SystemDir & '\shell32.dll'
; Struktur erzeugen um den Iconindex abzuspeichern
Local $stIcon = DllStructCreate("int")
Local $stString = DllStructCreate("wchar[260]")
Local $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)
Local $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)