Using Custom Data Structures in DLL Function Calls

Functions in dynamic link libraries use parameters of different data types. Some functions require passing values of simple data types like integer or boolean through their parameters, while other functions require passing custom structures. This topic explains how you can use custom data structures when calling DLL functions from TestComplete tests.

First of all, to create a data structure, you must define its data type in your test. For this purpose, call the DLL.DefineType method. It registers the new data type (normally, a structure) and returns its ID. The ID can be used later to define members of other structure types or DLL function parameters.

When calling DLL.DefineType, you need to specify the name of the new data type (the name is used later to create a variable of this type) and the list of structure members. The members are specified as Member type, Member name pairs separated by commas. The member names are used to access the structure members in scripts. That is why they must agree with the naming rules of the scripting language you are using. Also, member names must be unique within the structure. Member types are specified by special constants built in TestComplete (see DefineProc Method for the list of these predefined constants) or by IDs returned by previous calls to the DefineType method when defining other custom data types. Note that if a structure member is a pointer to a variable of some data type, you must specify the additional vt_byref constant when defining the member type (see the example below).

The following example illustrates how you can define a custom structure with members of different data types:

StructID = DLL.DefineType("MyStruct", # name of the new structure
                          VT_I4, "IntMember", # integer member
                          VT_BYREF | VT_R4, "FloatPointerMember", # pointer to float
                          MyStruct2ID, "MyStruct2Member") # structure MyStruct2

Make sure that you correctly specified the member types. Incorrect definition of data types may cause TestComplete to shut down when passing such structures to DLL functions (this happens because erroneous definitions may cause incorrect stack processing).

From the Parameter Types for C++ Routines and Structures and Parameter Types for Delphi Routines and Structures topics, you can learn which data type constants built in TestComplete correspond to some standard data types frequently used in C++ and Delphi applications.

Compilers can align structure members at certain addresses multiplied by 1, 2, 4 or more bytes. For instance, the double word (4 byte) alignment is often used in applications. The alignment may enlarge the actual size of structure members whose data type normally takes less memory than the alignment value. For instance, Boolean occupies one byte. In case of double word alignment, the actual size of a Boolean member will be four bytes. You should remember this and use appropriate data type constants (in this case, vt_b4 instead of vt_b1 for a Boolean member with double word alignment) when defining members of custom structures since TestComplete does not align structure members itself when passing them to a DLL function being called. The compilers use alignment for those structures that are defined by default, that is, without the use of the #pragma pack(...) statement in C++ code or packed record in Delphi. When creating a data type for the “default” structures in scripts, pay attention to the size of the structure members.

The DefineType method only registers the data type but does not create a variable of this type. To create a structure of the new type, call the DLL.New method. It creates and returns an object that represents the specified structure type in tests. The memory block allocated for the structure is filled with zero values. To access structure members and initialize them from tests, use the member names passed to the DefineType method when defining the structure type. The example below demonstrates how you can create and initialize a structure variable:

struct1 = DLL.New("MyStruct")

struct1.IntMember = 42
struct1.FloatPointerMember = pFloatVar
struct1.MyStruct2Member = MyStruct2Var

Note that the DLL.New method has the second parameter, Count, that is optional and not used in the example above. This parameter specifies the number of instances of the data type to create. Using the second parameter, you can create an array of elements of the specified data type. See Using Arrays in DLL Function Calls for details.

MyEnvironment = DLL.DefineEnvironment(True)
StructID = MyEnvironment.DefineType("MyStruct",
                          VT_I4, "IntMember",
                          VT_BYREF | VT_R4, "FloatPointerMember",
                          MyStruct2ID, "MyStruct2Member")
struct1 = MyEnvironment.New("MyStruct")

struct1.IntMember = 42
struct1.FloatPointerMember = pFloatVar
struct1.MyStruct2Member = MyStruct2Var;

After you defined the structure type, created and initialized a variable of this type, you can pass the structure through the parameters of the needed DLL function in the same manner as you pass parameters of any other data type. See Calling DLL Functions From Tests - Tutorial for more information on this.

See Also

Calling DLL Functions From Tests - Tutorial
Calling DLL Functions From Tests
Using String Parameters in DLL Function Calls