Funktionreferenz


DllCall

Beschreibung anzeigen in

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 8Bit Integer vorzeichenlos
BOOLEAN 8Bit Integer vorzeichenlos
SHORT 16Bit Integer mit Vorzeichen
USHORT 16Bit Integer vorzeichenlos
WORD 16Bit Integer vorzeichenlos
INT 32Bit Integer mit Vorzeichen
LONG 32Bit Integer mit Vorzeichen
BOOL 32Bit Integer mit Vorzeichen
UINT 32Bit Integer vorzeichenlos
ULONG 32Bit Integer vorzeichenlos
DWORD 32Bit Integer vorzeichenlos
INT64 64Bit Integer mit Vorzeichen
UINT64 64Bit Integer vorzeichenlos
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: Ein Array, siehe Bemerkungen.
Fehler: Setzt das @error Flag auf ungleich null.
@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.

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 ungleich 0 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

Wenn ein Ausgabeparameter vom Typ STR oder WSTR als Null-String definiert ist, wird nur ein Maximum von 65536 Strings zurückgegeben.

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

Verwandte Funktionen

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

Beispiel

Beispiel 1

; Direkter Aufruf der Nachrichtenfenster-API.
DllCall("user32.dll", "int", "MessageBox", _
        "hwnd", 0, _ ; Handle des Hauptfensters
        "str", "Some text", _ ; Der Text des Nachrichtenfensters
        "str", "Some title", _ ; Der Titel des Nachrichtenfensters
        "int", 0) ; Flags des Nachrichtenfensters

Beispiel 2

#include <MsgBoxConstants.au3>

;Aufrufen einer Funktion, die Parameter verändert
Local $iPID = Run("notepad")

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

If $hWnd = 0 Then
    ; Wartezeit abgelaufen.
    Exit MsgBox($MB_SYSTEMMODAL, Default, "Es ist nicht möglich den Editor zu starten!")
EndIf

Local $aResult = DllCall("user32.dll", "int", "GetWindowText", "hwnd", $hWnd, "str", "", "int", 32768)
MsgBox($MB_SYSTEMMODAL, Default, "Anzahl zurückgegebener Zeichen: " & $aResult[0])
MsgBox($MB_SYSTEMMODAL, Default, "Text (zurückgegeben in Parameter 2): '" & $aResult[2] & "'")

WinClose($hWnd)

Beispiel 3

#include <MsgBoxConstants.au3>

;Den Windows PickIconDlg anzeigen
Local $sFileName = @SystemDir & '\shell32.dll'

; Struktur erzeugen um den Iconindex abzuspeichern
Local $tIconIndex = DllStructCreate("int")
Local $tString = DllStructCreate("wchar[260]")
Local $iStructsize = DllStructGetSize($tString) / 2
DllStructSetData($tString, 1, $sFileName)

; Den PickIconDlg starten - '62' ist der Ordinalwert für diese Funktion
DllCall("shell32.dll", "none", 62, _
        "hwnd", 0, _
        "struct*", $tString, _
        "int", $iStructsize, _
        "struct*", $tIconIndex)

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

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