CallDll - method of the PmaDll object

Description:

Allows calling functions in DLL library, pass input/output parameters and obtain resulting value.

Syntax:

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

Parameters:

nAttr	(Long) Attributes to call a function. 0 - The function is defined in 32-bit DLL as __cdecl (in 64-bit is always as __fastcall, the value is ignored). 1 - The function is defined in 32-bit DLL as __stdcall (in 64-bit is always as __fastcall, the value is ignored).
nRetDt	(Long) Data type of returned value by the called function in DLL. 3 - Integer (1 - 4 bytes), a copy of the value is passed. 4 - Real number 4 bytes, a copy of the value is passed. 5 - Real number 8 bytes, a copy of the value is passed.
sName	(String) Name of the function called in DLL.
nParDt	[optional] (Long) Data type of corresponding parameter of the function called in DLL. 3 - Integer (1 - 4 bytes), a copy of the value is passed. 4 - Real number 4 bytes, a copy of the value is passed. 5 - Real number 8 bytes, a copy of the value is passed. 9 - Reference to the PmBuffer object representing the binary data. A pointer to the beginning of the binary data of the PmBuffer object is passed. If the called function modifies the content of the binary data (input/output) then the binary data is really changed in the PmBuffer object. In the C syntax, these are the parameters marked with characters * or &. These are used for input/output parameters, pointers to structures, but mostly for the pointers to text strings of the C language terminated by the NULL character. It means that if the parameter does not represent an elementary numeric value then it is always passed as individual PmBuffer.
vParVal	[optional] (Variant) The value of corresponding parameter of the function called in DLL.

Return values:

Returns value returned by the called function in DLL.

Note:

Caution! For each single parameter of the called function in DLL there are two corresponding parameters nParDt and vParVal in the CallDll method

Caution! Data types of the returned values and parameters, number of parameters and calling type must be set exactly according to the definition of the function in the DLL library. The implementation of the CallDll method does not check the definition of the method in DLL. If the calling is not exactly corresponding to the definition of the function in DLL then the application may crash.

Example1:

JavaScriptSelect and copy to clipboard


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

Example2:

Calling the OS Windows API function GetUserName that is located in the DLL library AdvApi32.dll. The function returns the name of user currently logged into OS Windows. The function is defined in C language as follows:

BOOL __stdcall GetUserName(LPSTR lpBuffer, LPDWORD pcbBuffer);

- The first parameter lpBuffer (output) represents a pointer to prepared memory block (buffer), where the text string containing the user name and terminated by the NULL character will be copied. The parameter will be handled by the PmBuffer object set to reasonable size (e.g. 256 characters).

- The second parameter pcbBuffer (input/output) represents a pointer to DWORD value (4 bytes integer). Before calling, the size (number of characters) of prepared buffer is set (PmBuffer.SetInt32). After calling, it will contain the number of copied characters including the NULL character (PmBuffer.GetInt32). The parameter will be handled by the PmBuffer object containing DWORD (4 bytes).

Example:

JavaScriptSelect and copy to clipboard


//C++ declaration of Win32 API function:
//int __stdcall GetUserNameW(char* psName, unsigned long* pnLength);

var oName = Pm.CreatePmBuffer();  //Must be the PmBuffer object because psName is text string
oName.SetSize(256 * 2);

var oLen = Pm.CreatePmBuffer();  //Must be the PmBuffer object because pnLength is 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);