Basics of Using API Functions

Introduction

On the surface, using a function from the Windows API in a Visual Basic program seems fairly simple and straightforward. (Don't worry -- we'll get to the complicated stuff soon enough!) Before you begin using the function, you must first declare it somewhere in your program. Then, you can use the function just as you would any other function in Visual Basic. This page explains how to declare a function and demonstrates some simple examples of how to use them in code.

Declaring the Function

Before an API function can be using in Visual Basic, it must first be declared. By declaring the function, you tell Visual Basic where it can find the function. The declaration identifies the name of the function, the DLL file it appears in, the parameters it requires, and the data type (if any) it returns. Armed with this information, Visual Basic knows where to find the API function whenever it is invoked. (This procedure isn't limited to Windows API functions. If you import any functions from a DLL file, they must be declared in the same manner. Using other DLL function libraries is not covered by this site.)

The below statement illustrates the syntax of the declaration. The Declare statement in Visual Basic is used to declare a function. The Declare statement can only appear in the (declarations) section of a form or module. If it appears in a form, the declaration must be Private, making the function only available inside that form. If it appears in a module, the declaration can be either Public or Private. The Public keyword makes the function available throughout the entire program, whereas the Private keyword restricts its use to within the module itself.

[{Public | Private}] Declare Function function_name Lib "DLL_filename" [Alias "function_alias"] (argument_list) As data_type

Since this syntax might seem intimidating at first, the following list identifies the various components of the Declare statement.

function_name: The name of the API function. This is the name by which Visual Basic will refer to the function everywhere else in your code. In theory, you can make this any name you want (as long as you use the proper Alias clause), but it's safest to make this the "official" name of the function in the Windows API.
DLL_filename: The name of the DLL file which stores the function. This does not include the path, because the Windows System directory (where all API DLL files appear) is assumed. Actually, the filename does not even have to specify the .dll extension, so user32 and user32.dll are synonymous. However, watch out for some API functions which do not occur in DLL files; for example, some printer-using API functions appear in winspool.drv. In cases like that, the extension must be specified.
function_alias: (Optional) The name of the function as it appears in the DLL file. This is important because almost every function which has a string as a parameter has two versions: the ANSI version (used by most speaking languages) and the Unicode wide-character version (used by wide-character set languages such as Chinese). Since this web site is designed primarily for English speakers, the ANSI version of the functions are always used. When an ANSI/Unicode pair appear in a DLL, they are given slightly different names: the ANSI version ends with the letter A, and the Unicode version ends with the letter W. For example, the two versions of CompareString are called CompareStringA and CompareStringW.
argument_list: A list of the zero or more arguments which the function needs. This is very similar to any other argument list in Visual Basic, but its added features in the Declare statement will be discussed in the next section.
data_type: The name of the data type which the function returns. This will almost always be a Long, although a few function returns a String.

In case you were wondering, some functions do not return any value. For those functions, the Declare statement takes a slightly different format, presented below.

[{Public | Private}] Declare Sub function_name Lib "DLL_filename" [Alias "function_alias"] (argument_list)

The Argument List

The argument list specifies how many and what kinds of variables are passed to the function. Its format is very similar to the argument list of a program-defined Function or Sub. The following line illustrates the syntax of the argument list. Keep in mind that some functions take an empty argument list -- they are not passed any data whatsoever.

[{ByVal | ByRef}] argument_name As data_type, ...

Except for the option for ByVal and ByRef, which will be introduced shortly, the format of the argument list is similar to what you are probably used to already. But for review, here's what the different symbols in the argument list syntax represent.

argument_name: The name given to the argument. When declaring API calls, this really only serves to give a clue as to what the parameter represents. Although you should use the argument name suggested by this guide (or by other API documentation), you are actually free to choose whatever name you wish.
data_type: The data type of the individual argument. This could also be the "Any" keyword, which allows information in any data type to be passed.

Data Types

As you already know, a data type specifies the size and format of a variable or argument to a function. API functions support only a limited number of data types compared to those available in Visual Basic. The following list identifies which data types can be used in API function declarations.

Byte: An 8-bit integer.
Integer: A 16-bit integer.
Long: A 32-bit integer.
String: A variable-length string.

In addition to the aforementioned data types, any of the API structures can also be used. Structures will be dealt with in a later page in this introduction. Out of the four data types mentioned above, Long and String are the most common. Since Windows is a 32-bit operating system (starting with Windows 95 and Windows NT 3.1), almost all numbers used in its API are Longs, 32-bit integers. Strings are also used frequently because they are pretty much the only way to store strings.

ByVal and ByRef: An Introduction

The ByVal and ByRef keywords specify the method used to pass a parameter to the API function. These two methods are extremely different and nonsubstitutable -- you can never use ByRef in place of ByVal and vice versa. When declaring API functions, the ByRef method is assumed to be used unless the ByVal keyword is used explicitly. Therefore, in API function declares, you will usually never see ByRef explicitly used; it will only be apparent by the lack of the ByVal keyword.

The actual meanings of ByVal and ByRef are beyond the scope of this individual page, although knowledge of their actual interpretations is crucial for using the more sophisticated API functions. At this point, however, the gist of these two keywords can be summarized as follows.

ByVal literally means "By Value." The value of whatever variable or expression is passed as the parameter. This method prevents the function from altering the contents of a variable passed ByVal. For example, if you have a variable MyVar that you pass ByVal to an API function, the API function cannot possibly edit the contents of MyVar.

ByRef literally means "By Reference." Instead of passing the contents of the variable, this method passes a sort of reference to the variable itself. This allows the function to edit the contents of the variable passed as that parameter. Note that expressions or constants cannot be passed ByRef -- only variables. For example, a variable MyVar passed ByRef to an API function may very well be edited by that function. In fact, ByRef parameters are usually used to allow the function to "return" information outside its single return value.

There are a few additional points to remember about ByVal and ByRef:

Strings are always passed ByVal. However, the API function is able to edit the contents of the string variable, as if it had been passed ByRef. The reasons for this are beyond the scope of this page.
User-defined structures, including structures used by the API, are always passed ByRef.
Arrays are always passed ByRef when the entire array is meant to be passed to a function. When passing an entire array to a function, VB syntax mandates that you "pass" the first element of the array to the function. However, in reality you are passing the entire array if that parameter is defined to by ByRef. If the parameter is instead ByVal, passing the first element of the array does just that.
Numeric variables can be passed either ByVal or ByRef, depending on the requirements of the function.

Examples

This page has presented a lot of information about the Declare statement in Visual Basic. At first, using Declare may seem very difficult, especially since I am saving some of the uglier details for a later page of this API introduction series. Fortunately, you probably will never write a Declare yourself. You can get the Declares for API functions from the API Text Viewer that comes with Visual Basic, or you can get the Declares off the pages of this site. With these resources, declaring API functions becomes just a copy-and-paste operation. Nevertheless, a number of examples of the Declare statement will help you understand the contents of this page.

The following list presents a number of examples of the Declare statement as well as a brief explanation of what they mean. Don't worry about what these functions actually do at this point, although you can read about any of them elsewhere in this site. What's important here is understanding the mechanics of the Declare statement.

The following line declares a function which does not take any parameters and returns a 32-bit integer:
Declare Function GetDesktopWindow Lib "user32.dll" () As Long
The following line declares a function which takes a single 32-bit parameter by value and does not have a return value:
Declare Function Sleep Lib "kernel32.dll" (ByVal dwMilliseconds As Long)
The following line declares a function which takes two 32-bit parameters by value and returns another 32-bit integer:
Declare Function ReleaseDC Lib "user32.dll" (ByVal hWnd As Long, ByVal hDC As Long) As Long
The following line declares a function which takes one string as a parameter and returns another string. Notice how this function, like almost all string-using API functions, requires an alias:
Declare Function CharUpper Lib "user32.dll" Alias "CharUpperA" (ByVal lpsz As String) As String
The following line declares a function which takes one RECT structure as a parameter and returns a 32-bit integer:
Declare Function CreateRectRgnIndirect Lib "gdi32.dll" (lpRect As RECT) As Long
The following line declares a function which takes three parameters. The first two parameters are 32-bit integers passed by value. The third parameter is a 32-bit integer passed by reference -- that variable's value is set by the function. The function also returns a 32-bit integer:
Declare Function SHGetSpecialFolderLocation Lib "shell32.dll" (ByVal hwndOwner As Long, ByVal nFolder As Long, ppidl As Long) As Long
Finally, this declaration encompasses a number of different ideas simultaneously:
Declare Function RegCreateKeyEx Lib "advapi32.dll" Alias "RegCreateKeyExA" (ByVal hKey As Long, ByVal lpSubKey As String, ByVal Reserved As Long, ByVal lpClass As String, ByVal dwOptions As Long, ByVal samDesired As Long, lpSecurityAttributes As SECURITY_ATTRIBUTES, phkResult As Long, lpdwDisposition As Long) As Long

That completes this section of the Introduction to the Windows API. If that last example declaration confuses you, you should review the contents of this page to cover any ideas which are still fuzzy. Remember, the rest of this series of pages builds on the fundamentals outlined above.

<< Back to Part 1 | Contents of Introduction | Forward to Part 3 >>

Go back to the Articles section index.
Go back to the Windows API Guide home page.

Last Modified: January 12, 2000
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000
Go back to the Windows API Guide home page.
E-mail: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vb-world.net/articles/intro/part02.html