CallDll - metoda objektu PmaDll

Popis:

Umožňuje volat funkce v DLL knihovně, předat vstupní nebo vstupně/výstupní parametry a získat vrácenou hodnotu.

Syntaxe:

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

Parametry:

nAttr	(Long) Atributy jak volat funkci. 0 - Funkce je v 32-bit DLL deklarována jako __cdecl (v 64-bit je vždy jako __fastcall, hodnota je ignorována). 1 - Funkce je v 32-bit DLL deklarována jako __stdcall (v 64-bit je vždy jako __fastcall, hodnota je ignorována).
nRetDt	(Long) Datový typ vrácené hodnoty volané funkce v DLL. 3 - Celé číslo (1 - 4 bajty), předává se kopie hodnoty. 4 - Reálné číslo 4 bajty, předává se kopie hodnoty. 5 - Reálné číslo 8 bajtů, předává se kopie hodnoty.
sName	(String) Název volané funkce v DLL.
nParDt	[nepovinné] (Long) Datový typ příslušného parametru volané funkce v DLL. 3 - Celé číslo (1 - 4 bajty), předává se kopie hodnoty. 4 - Reálné číslo 4 bajty, předává se kopie hodnoty. 5 - Reálné číslo 8 bajtů, předává se kopie hodnoty. 9 - Reference na PmBuffer objekt, představující binární data. Předává se ukazatel na začátek vlastních binárních dat objektu PmBuffer. Pokud volaná funkce změní obsah binárních dat (vstupně/výstupní), pak se změní skutečně přímo v binárních datech v objektu PmBuffer. V syntaxi C se jedná o parametry označené znaky * nebo &. Realizují se tak vstupně/výstupní parametry, ukazatele na struktury, ale hlavně také ukazatele na textové řetězce jazyka C ukončené znakem NULL. To znamená, že pokud parametr nepředstavuje elementární číselnou hodnotu, pak se předává vždy jako samostatný PmBuffer.
vParVal	[nepovinné] (Variant) Hodnota příslušného parametru volané funkce v DLL.

Vrácená hodnota:

Vrací hodnotu, kterou vrátila volaná funkce v DLL.

Poznámka:

Upozornění! Každému jednomu parametru volané funkce v DLL odpovídá dvojice parametrů nParDt a vParVal v metodě CallDll

Upozornění! Datové typy vrácené hodnoty i parametrů, počet parametrů, typ volání, vše musí být nastaveno přesně podle deklarace funkce v DLL knihovně.
Implementace metody CallDll nekontroluje tvar funkce v DLL.
Pokud nebude volání v souladu s deklarací funkce v DLL, pak může dojít k pádu aplikace.

Příklad1:

JavaScriptVyber a zkopíruj do schránky



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

Příklad2:

Volání API funkce OS Windows GetUserName, která je umístěna v DLL knihovně AdvApi32.dll.
Funkce vrací jméno přihlášeného uživatele v OS Windows.
Funkce je v jazyce C deklarována následovně:
BOOL __stdcall GetUserName(LPSTR lpBuffer, LPDWORD pcbBuffer);

- První parametr lpBuffer (výstupní) představuje ukazatel na předem připravený paměťový blok (buffer), do kterého bude nakopírován textový řetězec ukončený znakem NULL obsahující jméno uživatele.
Parametr bude realizován objektem PmBuffer nastaveným na rozumnou velikost (např. 256 znaků).

- Druhý parametr pcbBuffer (vstupně/výstupní) představuje ukazatel na DWORD hodnotu (celé číslo 4 bajty).
Před voláním se nastaví velikost připraveného bufferu ve znacích (PmBuffer.SetInt32).
Po volání bude obsahovat počet zkopírovaných znaků včetně znaku NULL (PmBuffer.GetInt32).
Parametr bude realizován objektem PmBuffer obsahujícím DWORD (4 bajty).

Příklad:

JavaScriptVyber a zkopíruj do schránky



// C++ declaration of Win32 API function:

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


var oName = Pm.CreatePmBuffer();
  // Musí být objekt PmBuffer, protože psName je textový řetězec

oName.SetSize(256 * 2);


var oLen = Pm.CreatePmBuffer();
  // Musí být objekt PmBuffer, protože pnLength je reference (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);