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.

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.

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.)
