Before we dive into the examples of using specific API functions, let’s go over the fundamental concepts. The Win 32 API consists of functions, structures, and messages that can be accessed to build Windows 95/98 and Windows NT applications.
The four functional categories of the Windows API are:
- Windows Management (User)
- Graphics Device Interface (GDI)
- System Services (Kernel)
- Multimedia (MMSystem)
The function in these categories are implemented as DLLs (Dynamic Link Libraries) and can be called from any language. A DLL is loaded at runtime and it doesn’t need to be linked to your application. Actually, that’s where the name comes from: the contents of a DLL are linked to your application dynamically at runtime, not at design time. Because the API functions are required for the proper operation of Windows itself, the DLLs are always available to your application.
Windows Management provides the essential functions to build and manage your applications. All the basic input and output of the system goes through this layer of the Win32 API, including mouse and keyboard input and all processing of messages sent to your application. The Windows Management functions give your application better control over the mouse movement than Visual Basic’s mouse events.
The Graphics Device Interface provides the functions you use to manage all supported graphical devices on your system, including the monitor and printer. In addition, you can define fonts, pens, and brushes. The GDI provides support for the line and circle drawing operations and for bit-blit operations with the BitBlt() function. (For details on bit-blt, see the discussion of the PaintPicture method in Chapter 7, Manipulating Color and Pixels with Visual Basic.)
System Services provides functions to access the resources of the computer and the operating system. You’ll see how to call some of these functions to figure out the free resources on the system running your application.
The Multimedia functions allow you to play waveform audio, MIDI music, and digital video. You can achieve this with the MCI command string and MCI command message interface, which are discussed in detail in Appendix B on the CD, Using Multimedia Elements to Enhance Applications.
Accessing Win32 API from Visual Basic
The only difference between Visual Basic functions and the Win32 API functions is that API functions must be declared before they can be used. In essence, you must tell Visual Basic the name and location of the DLL in which an API function resides and the arguments it requires. You can then use it as you would use any other Visual Basic function.
Declaring API Functions
You declare the Win32 API functions with the Declare statement. One way is to enter the function along with the arguments, as in the following:
The Win32 API function mciSendString() is part of the Winmm multimedia library (which is in the Winmm.dll file in the Windows/System folder). The A suffix is a leftover from older versions of the API, where 16- and 32-bit functions coexisted. Under Windows 95/98, you must use 32-bit functions and ignore the alias of the function.
Nearly all API functions have their arguments passed by value. Only arguments that must be modified by the function are passed by reference. By default, Visual Basic passes arguments by reference, so you must always precede the argument names with the ByVal keyword.
Using the API Viewer Application
You aren’t expected to remember the arguments of every API function or even the function names. It’s assumed you’ll look them up in a reference. The reference is available from within Visual Basic’s IDE, and it’s the API Viewer shown in Figure 13.1.
You can easily copy and paste any function into your Visual Basic programs. To do so, follow these steps:
- You can easily copy and paste any function into your Visual Basic programs. To do so, follow these steps:
- In the API Viewer window, choose File» Load Text File or File» Load Database File. the Load Database File loads faster (except for the first time, when the test file is converted to a database).
- In the Available Items list box, select the function you want, and click the Add button. API Viewer displays the selected function(s) in the Selected Items list box.
- Select the functions you need for your application and then click the Copy button to copy the function’s.declaration to the Clipboard .
- Open your application’s Code window and paste in the function declarations.
Most of the API functions require a large number of arguments and some of the arguments can be complicated data types. The argument types of the API functions are described the next.
API Function Arguments
When using the Win32 API functions, you must supply the functions declarations and their arguments. The Win32 API was written for programmers writing in the C or C++ language, so the documentation uses the C data structures, which you must map to their Visual Basic equivalents. Table 13.1 summarizes the C declarations and the corresponding Visual Basic data types. The third column shows how the arguments are passed to the API function. All types are passed by value, except Internet and Long Integer pointers.
Passing Arguments by Value
To use API functions in your code, you must understand two argument-passing mechanisms, ByVal and ByRef. They are explained in detail in Chapter 3, Visual Basic: The Language, but I’m including an overview of Visual Basic’s argument passing mechanisms in this section.
When you pass arguments by value, you pass a copy of the argument to the called procedure. The procedure can change the value, but the change affects only the copy, not the argument itself. Visual Basic uses the ByVa/ keyw rd to indicate that the argument is passed by value. Code 13.1 shows the AnySub() procedure with the ‘argument anyNumber passed by value. Within the AnySub() procedure, the argument anyNumber is set to the value 10. When the program exits this procedure, however, anyNumber reverts to its assigned value.
Passing Arguments by Value
Code 13.1:
The print statement in the AnySub() procedure displays the value assigned to the anyNumber variable from within its code. The main program displays the value] on the Immediate window: The value 10 of the procedure’s argument takes effect only while AnySub() executes; it’s invalid outside of the procedure. .
Passing Arguments by Reference
When you pass arguments by reference, you give the procedure access to the actual contents of the argument. The procedure to which the argument is passed has the actual memory address where the argument resides and can Permanently change the value of the argument. In Visual Basic, this is the default argument-passing mechanism. The AnySub() procedure in the following example changes the value of its argument permanently.
Passing Arguments by Reference
Coded 13.2:
If you call this subroutine with the following lines:
The Print statements will display the following lines in the Debug window:
Before calling AnySub x = 4
After calling AnySub x = 20.
The changes made to the x variable in the AnySub() subroutine have a global effect because the argument is passed by reference. If the called procedure has no reason to change the value of an argument, the argument must be passed by value. Some API functions store results in their’ arguments. These’ functions expect that their arguments will be passed by reference-In C~these .arguments are called pointers (they point to the-memory location where the variable is stored).
