Calling Win32 API Functions

Basic Concepts

Important Notes

Requirements

You can call Win32 API functions from your TestComplete scripts. The available functions are shown in the Code Completion window under the Win32API node. The supported Win32 functions are displayed as methods of this object.

Only those Win32 functions are supported that are supported on all Win32 platforms (from Windows XP to Windows 10). TestComplete does not support functions exclusive to some platforms.

You can skip the object name (Win32API) when calling functions. For instance, the following two lines are equivalent:

clr = Win32API.GetSysColor(223)
clr = GetSysColor(223)

Note, however, that omitting the Win32API object name before the method name can cause method conflicts if another object, which allows skipping its name, provides the method with the same name. To solve the problem, put the Win32API object name before the function name. For example, to call the Win32 API Beep function, use the Win32API.Beep(…) notation rather than just Beep(…), otherwise TestComplete will call the Beep method of the aqUtils object.

• Since Microsoft OLE does not support pointers, you cannot use API functions that use pointer parameters or that return pointers to data structures. There is one exception: in some functions you can pass 0 as a pointer value. This trick can help you to call certain functions from your scripts, for instance, CreateDC.

  However, this limitation does not concern all the functions working with structures. The Win32API object contains specific methods (for instance, _DOCINFO) that create a program object which provide a scripting interface to the appropriate structures. You can then use this object to fill structure fields and to pass these structures to functions as parameters. For instance, you can call _DOCINFO to create an object for the DOCINFO structure and then pass this object to the StartDoc function as a parameter.

  Note:

  The nested structures are not supported. For instance, if a structure is used as a field of another structure, TestComplete does not provide a scripting interface to fields of this nested structure.

• If a parameter is passed by reference and used to return a value, the return value will not be available to scripts. See Object Properties, Fields and Methods That Are Unavailable to TestComplete for more information. All supported functions and structures are displayed in the Code Completion window as child items of Win32API. Since there is no difference in declaration between a parameter passed by reference (such as a record), and one that is passed by reference and used to return a value, Code Completion will also show the latter type of function, which is generally of no use to scripts.

  Note, however, that if a parameter passed by reference is a structure, you can use the function, to which this parameter belongs. TestComplete provides wrapper objects to work with some Win32 and VCL structures. You can pass these objects to functions and the functions will properly fill the structure fields. For more information, see Using Structures in Scripts.

• The corresponding Win32 API functions are executed directly by the platform and are not handled by TestComplete. Therefore, the user should specify valid parameters for these functions. For a detailed reference on Win32 API functions, see the Win32 API documentation in the MSDN library.

• Important: To get the path to the Windows directory, either use the Sys.OSInfo.WindowsDirectory property or call the aqEnvironment.GetEnvironmentVariable method to get the WinDir environment variable’s value. Do not use the GetWindowsDirectory API function for this purpose as it may make TestComplete shut down.

The Win32API scripting object and support for calling Win32 API functions are provided by default regardless of the TestComplete Modules you have installed. If the Win32API object is not available, choose File | Install Extensions from the TestComplete main menu and check whether the Win32API plugin is active.