Understanding API Data Types

One of the reasons the API routines are difficult to call is that Windows uses a slightly different set of data types than Visual Basic. Although the Windows API uses the String and Long data types, it also uses other data types such as RECT and MSG. Therefore, getting the format exact can be difficult.

note

Not only must your arguments match the required API argument list in number and data type, you must also pass the arguments in the proper way - either by value or by reference. Therefore, use the ByVal keyword when needed, because without ByVal, ByRef is assumed. Some arguments in the same API routine require different methods of passing.

The Alias keyword is used in a Declare statement to convert some string values that contain illegal characters to legal Visual Basic equivalents. The Alias keyword also serves to convert Windows API routine names that aren't allowed, such as _lopen (a valid Windows API name but an invalid Visual Basic procedure name) to the Visual Basic naming standard.

You'll run across strange data types that you may not recognize. Table 23.1 describes some of these data types that you'll run across when working with API routines. This table lists the data types that differ from Visual Basic's own data types.

Table 23.1. Special data types used by the API routines.

Data Type Description
ANY A Windows API routine that accepts different kinds of data types will list ANY for those data types. All ANY arguments are passed by reference, so you won't use the ByVal keyword.
ATOM Integer data. Always passed by value and described in an API routine's declaration as ByVal argument% or ByVal argument As Integer.
BOOL Long integer data. Always passed by value and described in an API routine's declaration as ByVal argument% or ByVal argument As Long.
CHAR Byte data. Always passed by value and described in an API routine's declaration as ByVal argument As Byte.
COLOREF Long integer data used for specifying color values. Always passed by value and described in an API routine's declaration as ByVal argument% or ByVal argument As Long.
DWORD Long integer data. Always passed by value and described in an API routine's declaration as ByVal argument% or ByVal argument As Long.
NULL Long integer data types used for uninitialized values. Described in an API routine's declaration as ByVal argument& and ByVal argument As Long.
LPSTR, LPCSTR Matches the String data type. Described in an API routine's declaration as ByVal argument$ or ByVal argument As String.
STRUCTURE Sometimes, you'll run across a strange API data type such as RECT, MSG, and UDT. These define complex data types that may be a collection of several other data types. Each structure-based API routine requires a special structure, and you'll have to look at the API routine's required arguments to know how to format them.

Remember that Table 23.1 contains only a few of the data types you'll find in the Windows API Declare statements. Given these special API routines and their numerous arguments, how are you possibly supposed to know which to use? The next section shows you how to use a special tool that comes with Visual Basic that lets you manage API routines.

caution

If the API routine requires a String data type, you should pass a string that you've defined as a fixed-length string with much padding in the string. For example, double the length of the longest string you ever expect the API routine to return and then declare the fixed string argument with that much space before passing the string to the API routine. (You don't need to worry about the string length if the routine does not modify the string in any way.)

Top Home