Integer Parameters

Most parameters in the Windows API are integers of one kind or another. C makes a distinction between signed and unsigned integers, but to Basic they’re all signed. You can assign all integers—signed and unsigned—to Integers and Longs. “Hammering Bits,” page 271, discusses some of the problems you might have dealing with integers when you think they are unsigned but Basic thinks they are signed.

In the Windows API, you usually pass integers by value using the ByVal attribute. Table 2-2 lists the kinds of integers you’ll see in the API documentation and shows how to handle them in Declare statements.

Windows API	Basic
int, INT	ByVal Long
UINT	ByVal Long
BOOL	ByVal Long
WORD	ByVal Integer
DWORD	ByVal Long
WPARAM	ByVal Long
LPARAM, LRESULT	ByVal Long
COLORREF	ByVal Long
ATOM	ByVal Integer
HANDLE and friends	ByVal Long
BYTE	ByVal Byte
char	ByVal Byte

Table 2-2. Integers in the Windows API.

For passing integers, the API contract is simple. Basic agrees to put integer values on the stack and never see them again. Windows can do whatever it wants with those values. All that can go wrong here is that you could pass an integer too large for an Integer type or a Long type. Basic will catch this error before it gets anywhere near Windows. Of course, you could always pass a value that a particular API function doesn’t understand, but Windows promises to fail politely and return an error code in these cases.

Here’s a simple integer example. The Win32 documentation shows FloodFill as follows:

BOOL FloodFill(
    HDC hdc,            // Handle of device context
    int nXStart,        // X-coordinate of starting position
    int nYStart,        // Y-coordinate of starting position
    COLORREF crFill     // Color of fill boundary
);

You declare it this way in Basic:

Declare Function FloodFill Lib “GDI32” (ByVal hdc As Long, _
    ByVal nXStart As Long, ByVal nYStart As Long, _
    ByVal crFill As Long) As Long

You don’t have much choice about how to declare this function, but you can choose how to declare any variables you plan to pass to it. Because you’re passing by value, Visual Basic can do type conversion on any variables you pass. For example, the X- and Y-coordinate variables could be stored in Integers. You’d need an awfully big monitor to be higher than 32,767 or lower than
-32,768 if you’re measuring in pixels. I hope to have such a monitor on my
desk someday, but for now I consider it fairly safe to use Integer variables. Basic will convert them to Longs before passing them to FloodFill.

I use the Windows version of Hungarian in sample declarations, although I don’t like it. “Basic Hungarian,” page 16, explains what I don’t like and how my version of Hungarian differs. Apologies for any confusion this causes. The parameter names in declarations are ignored anyway, and I thought it would be better for my declarations to match the API documentation. Besides, I created a lot of my Declare statements by cutting, pasting, and modifying C prototypes, and I was too lazy to change the names.