Parameter Types for Delphi Routines and Structures

Applies to TestComplete 15.20, last modified on January 13, 2022

This topic illustrates how you can specify parameter and member types for Delphi 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 Delphi routines and structures located in DLLs, keep in mind the following specifics:

  • Delphi compiler 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 Boolean member, you should specify its type as vt_b4 instead of vt_b1.

    By default, the compiler uses alignment for those structures that are defined by default, that is, without the use of the packed record 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).

  • 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 or IDLLAccessProcess.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 the New 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 Delphi 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
AnsiChar vt_ui1
AnsiString vt_lpstr
This type is only supported for function parameters. The AnsiString result values are not supported.
Boolean vt_b1
BSTR vt_bstr
Byte vt_ui1
ByteBool vt_b1
Cardinal vt_ui4
Char vt_i1
Currency vt_cy
Double vt_r8
DWord vt_ui4
HResult vt_ui4 (HRESULT is not a Variant-compatible type, so in order for you to be able to work with HRESULT data, declare them as vt_ui4, not as vt_hresult.)
HWND vt_ui4 (for 32-bit DLLs)
-- or --
vt_ui8 (for 64-bit DLLs)
IDispatch vt_dispatch (see also Returning Interface References From DLL Functions)
Integer vt_i4
-- or --
vt_int
Int64 vt_i8
LongBool vt_b4
Longint vt_i4
-- or --
vt_int
Longword vt_ui4
OleVariant vt_variant
PByte vt_byref | vt_ui1
PChar vt_lpstr
-- or --
vt_byref | vt_i1
This type is only supported for function parameters. The PChar result values are not supported.
PWChar vt_lpwstr
PInteger vt_byref | vt_int
PVariant vt_byref | vt_variant
Real
(8-byte Real, not Real48)
vt_r8
Single vt_r4
Smallint vt_i2
string The string type is not supported.
TDateTime vt_date
Variant vt_variant
VARIANT_BOOL vt_bool
WideChar vt_ui2
WideString vt_bstr
Word vt_ui2
WordBool vt_b2

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

Highlight search results