This topic illustrates how you can specify parameter and member types for C++ routines and structures when calling DLL functions from TestComplete tests. The complete explanation of specifying the types is included in the description of IDefineDLL.DefineProc
.
Important Notes
When specifying parameter and member types for C++ routines and structures located in DLLs, keep in mind the following specifics:
-
The table below in the topic holds examples of data types used in Microsoft Visual C++ v. 6.0. The size of some types may differ from one compiler to another or even from one version of a compiler to another version of the same compiler. If you doubt of the type size, refer to the documentation of your compiler.
-
C++ compilers can align structure members at certain bounds: at bytes, words, double words, etc. For instance, applications often use double word alignment. In this case the address of each member is a multiple of 4. So, if a structure has a bool member, you should specify its type as
vt_b4
instead ofvt_b1
. TestComplete does not align structure members itself.By default, the compiler uses alignment for those structures that are defined by default, that is, without the use of the
#pragma pack(...)
statement. So, when creating a data type for the “default” structures in scripts, pay attention to the size of the structure members. -
Make sure you specified the parameter types correctly. Defining the parameter types incorrectly may cause TestComplete to shut down (this happens because erroneous definitions cause incorrect stack processing).
-
The
void *
type is not a Variant-compatible type and it is not supported. -
For JavaScript, JScript, Python, C#Script and C++Script users: These scripting languages do not support passing variables by references through parameters of a function being called. Therefore, you cannot pass a variable of an ordinary data type (like integer, boolean, etc.) by a reference to a DLL routine and get the value modified by the routine in your JavaScript, JScript, Python, C#Script or C++Script (this restriction applies to C#Script and C++Script too since these languages are based on JScript and use the JScript engine) test. In this case, the value of the variable passed to the DLL routine from your JavaScript, JScript, Python, C#Script or C++Script test actually remains the same after the routine execution is over because the routine works with a copy of the variable.
However, objects are passed through routine parameters by references in these languages, and if the callee routine modifies some members of an object passed through its parameters, the caller routine can access the updated object. Therefore, if you pass a custom structure, array or string value created by the
DLL.New
orIDLLAccessProcess.New
method (see Using Custom Data Structures in DLL Function Calls, Using Arrays in DLL Function Calls and Using String Parameters in DLL Function Calls) from your JavaScript, JScript, Python, C#Script or C++Script test to a DLL routine, you can then access the modified structure, array or string after the routine execution is over. The point is that such structures, arrays and strings are created by theNew
methods as wrapper objects and such objects passed to a DLL routine can be modified and returned from the routine to which they are passed by references. -
In Python, all constants are capitalized. So, you write VT_BYREF, VT_R4 and so on.
Parameter Types
The following table shows correspondences between Microsoft Visual C++ v. 6.0 data types and special constants used in TestComplete when calling the IDefineDLL.DefineProc
, DLL.DefineType
and IDLLAccessProcess.DefineType
methods to specify data types of DLL functions’ parameters or members of structures defined in DLLs.
Type | Constant |
---|---|
bool | vt_b1 |
BSTR | vt_bstr |
BSTR * | vt_byref | vt_bstr |
Byte | vt_ui1 |
Byte * | vt_byref | vt_ui1 |
char | vt_i1 |
char * | vt_lpstr -- or -- vt_byref | vt_i1 This type is supported for function parameters only. The char * result type is not supported. |
CLSID | vt_clsid |
CLSID * | vt_byref | vt_clsid |
CY | vt_cy |
CY * | vt_byref | vt_cy |
DATE | vt_date |
DATE * | vt_byref | vt_date |
DECIMAL | Not supported. |
double | vt_r8 |
double * | vt_byref | vt_r8 |
float | vt_r4 |
float * | vt_byref | vt_r4 |
HRESULT | vt_ui4 (HRESULT is not a Variant-compatible type. If the function to be called uses this type, declare it as vt_ui4 , but not as vt_hresult ). |
HRESULT * | vt_byref | vt_ui4 (HRESULT is not a Variable-compatible type. If the function to be called uses HRESULT * , declare it as vt_byref | vt_ui4 , but not as vt_byref | vt_hresult ). |
HWND | vt_ui4 (for 32-bit DLLs)-- or -- vt_ui8 (for 64-bit DLLs) |
HWND * | vt_byref | vt_ui4 (for 32-bit DLLs)-- or -- vt_byref | vt_ui8 (for 64-bit DLLs) |
IDispatch * | vt_dispatch |
IDispatch ** | vt_byref | vt_dispatch |
int | vt_int |
int * | vt_byref | vt_int |
long | vt_i4 |
long * | vt_byref | vt_i4 |
long long | vt_i8 |
long long * | vt_byref | vt_i8 |
LPCSTR | vt_lpstr |
LPCSTR * | vt_byref | vt_lpstr |
LPCTSTR | vt_lpstr (for ANSI)-- or -- vt_lpwstr (for Unicode) |
LPCTSTR * | vt_byref | vt_lpstr (for ANSI)-- or -- vt_byref | vt_lpwstr (for Unicode) |
LPCWSTR | vt_lpwstr |
LPCWSTR * | vt_byref | vt_lpwstr |
LPSTR | vt_lpstr |
LPSTR * | vt_byref | vt_lpstr |
LPTSTR | vt_lpstr (for ANSI)-- or -- vt_lpwstr (for Unicode) |
LPTSTR * | vt_byref | vt_lpstr (for ANSI)-- or -- vt_byref | vt_lpwstr (for Unicode) |
LPWSTR | vt_lpwstr |
LPWSTR * | vt_byref | vt_lpwstr |
SCODE | vt_error |
short | vt_i2 |
short * | vt_byref | vt_i2 |
unsigned int | vt_uint |
unsigned int * | vt_byref | vt_uint |
unsigned long | vt_ui4 |
unsigned long * | vt_byref | vt_ui4 |
unsigned long long | vt_ui8 |
unsigned long long * | vt_byref | vt_ui8 |
unsigned short | vt_ui2 |
unsigned short * | vt_byref | vt_ui2 |
VARIANT | vt_variant |
VARIANT * | vt_byref | vt_variant |
VARIANT_BOOL | vt_bool |
VARIANT_BOOL * | vt_byref | vt_bool |
wchar_t | vt_ui2 |
wchar_t * | vt_byref | vt_ui2 -- or -- vt_lpwstr |
See Also
Calling DLL Functions From Tests
Calling DLL Functions From Tests - Overview
Calling DLL Functions From Tests - Tutorial
Returning Interface References From DLL Functions