CallDll - metoda obiektu PmaDll

Opis:

Umożliwia wołać funkcje w bibliotece DLL, przekazać wejściowe lub wejściowo/wyjściowe parametry oraz uzyskać wartość zwrotną.

Składnia:

Variant CallDll(Long nAttr, Long nRetDt, String sName, [Long nParDt], [Variant vParVal])

Parametry:

nAttr	(Long) Atrybuty wołania funkcji. 0 - Funkcja w 32-bit DLL jest deklarowana jako __cdecl (w 64-bit jest zawsze jako __fastcall, wartość jest zignorowana). 1 - Funkcja w 32-bit DLL jest deklarowana jako __stdcall (w 64-bit jest zawsze jako __fastcall, wartość jest zignorowana).
nRetDt	(Long) Typ danych wartości zwrotnej wołanej funkcji w DLL. 3 - Liczba całkowita (1 - 4 bajty), zostanie przekazana kopia wartości. 4 - Liczba rzeczywista 4 bajty, zostanie przekazana kopia wartości. 5 - Liczba rzeczywista 8 bajtów, zostanie przekazana kopia wartości.
sName	(String) Nazwa wołanej funkcji w DLL.
nParDt	[opcjonalne] (Long) Typ danych odpowiedniego parametru wołanej funkcji w DLL. 3 - Liczba całkowita (1 - 4 bajty), zostanie przekazana kopia wartości. 4 - Liczba rzeczywista 4 bajty, zostanie przekazana kopia wartości. 5 - Liczba rzeczywista 8 bajtów, zostanie przekazana kopia wartości. 9 - Odniesienie do PmBuffer obiektu, reprezentującego dane binarne. Marker zostanie ustawiony na początek danych binarnych obiektu PmBuffer. Jeżeli wołana funkcja zmieni zawartość danych binarnych (wejściowo/wyjściowe), wtedy zostaną one zmienione bezpośrednio w danych binarnych w obiekcie PmBuffer. W składni C chodzi o parametry oznaczone znakami * lub &. Wtedy realizowane są wejściowo/wyjściowe parametry, markery struktury, ale przede wszystkim również markery łańcuchów tekstowych języka C zakończone znakiem NULL. To znaczy, że jeżeli parametr nie reprezentuje elementarną wartość liczbową, wtedy przekazywany jest zawsze jako samodzielny PmBuffer.
vParVal	[opcjonalne] (Variant) Wartość odpowiedniego parametru wołanej funkcji w DLL.

Wartość zwrotna:

Zwraca wartość, którą zwróciła wołana funkcja w DLL.

Notatka:

Uwaga! Odpowiednikiem każdego parametru wołanej funkcji w DLL jest para parametrów nParDt oraz vParVal w metodzie CallDll

Uwaga! Typy danych wartości zwrotnej oraz parametrów, ilość parametrów, typ wołania, to wszystko musi być ustawione według opisu funkcji w bibliotece DLL.
Implementacja metody CallDll nie sprawdza składnię funkcji w DLL.
Jeżeli jej wołanie nie będzie zgodne ze składnią funkcji w DLL, wtedy może spowodować zatrzymanie aplikacji.

Przykład1:

JavaScriptWybierz oraz skopiuj do schowka



var vVar = oDll.CallDll(nAttr, bRetDt, sName, nParDt, vParVal);

Przykład2:

Wołanie funcji API SO Windows GetUserName, która znajduje się w bibliotece DLL AdvApi32.dll.
Funkcja zwraca nazwę zalogowanego użytkownika SO Windows.
Funkcja jest określona w języku C następująco:
BOOL __stdcall GetUserName(LPSTR lpBuffer, LPDWORD pcbBuffer);

- Pierwszy parametr lpBuffer (wyjściowy) przedstawia marker na wcześiej przygotowany blok pamięci (buffer), do którego zostanie skopiowany łańcuch tekstowy zakończony znakiem NULL zawierający nazwę użytkownika.
Parametr będzie zrealizowany poprzez obiekt PmBuffer ustawiony na rozsądną wielkość (np. 256 znaków).

- Drugi parametr pcbBuffer (wejściowo/wyjściowy) przedstawia marker na wartość DWORD (liczba całkowita 4 bajty).
Przed wywołaniem zostanie ustawiona wielkość przygotowanego bufora w znakach (PmBuffer.SetInt32).
Po wywołaniu będzie zawierać ilość skopiowanych znaków włącznie znaku NULL (PmBuffer.GetInt32).
Parametr będzie zrealizowany poprzez obiekt PmBuffer zawierający DWORD (4 bajty).

Przykład:

JavaScriptWybierz oraz skopiuj do schowka



// C++ declaration of Win32 API function:

// int __stdcall GetUserNameW(char* psName, unsigned long* pnLength);


var oName = Pm.CreatePmBuffer();
  // Musi być obiekt PmBuffer, ponieważ psName jest łańcuch tekstowy

oName.SetSize(256 * 2);


var oLen = Pm.CreatePmBuffer();
  // Musi być obiekt PmBuffer, ponieważ pnLength jest odniesienie (pointer)

oLen.SetInt32(-2, oName.GetSize()/2);


pMe.Pm("../AdvApi32").CallDll(0, 3, "GetUserNameW", 9, oName, 9, oLen);


var sName = oName.GetStringVar(0, 0, 2);

Pm.Debug("Dll:GetUserName=" + sName);