Windows API Guide: Reference | Windows API Guide - Reference - Volume 1: Version 3.0 For the MS-DOS and PC-DOS Operating Systems

What is an API?

The acronym API stands for Application Programming Interface. It serves as a software interface to be used by other programs. Just as a number keypad is the interface for a calculator, an API is the software interface for things such as operating systems. The API of an operating system is the fundamental reason why different operating systems are incompatible -- why, for example, a Macintosh-based piece of software cannot run on a system running Windows 98 (without an emulator, at least). Because Mac OS and Windows have completely different APIs, programs designed to use one cannot use the other. The core function of an emulator is "converting" the API calls of one program into the API calls of the operating system running it; it acts as a sort of translator between the two APIs.

An API is truly the fundamental level of higher-level programming. In high-level programming, a program often does not execute tasks itself but instead tells some other program to do it. In the case of operting systems, programs frequently delegate various tasks to the underlying operating system. For example, if a program wishes to write data to a disk, it does not manually send commands to the hard disk itself to seek, read, write, etc. bit by bit. Instead, is merely tells the operating system to write a certain amount of data to a specified file, and the operating system handles the dirty work. The advantages of this arrangement are obvious. Designers of software do not have to worry about the basic, fundamental chores involved in every program (such as disk access, memory allocation, drawing on the monitor, etc.) by hand, saving both time and final program size. Also, suppose that a more efficient way to render an image on a monitor is created. If each individual program directly handled all its graphical output, each program would need to be updated to take advantage of this development. Instead, if they all use the API, and the operating system is upgraded to include this new method, every program now enjoys the benefits of the more efficient system without a single modification.

What Does the Windows API Do?

Basically, the Windows API handles everything that makes Windows what it is. Naturally, it encompasses aforementioned things such as drawing on the monitor, disk access, printer interface, Internet usage, etc. However, it also provides most of the features common to all Windows-based software. For example, the common dialog boxes (Open, Save As, Choose Font, etc.), the Windows shell, list boxes, operating system settings, and even windows themselves are provided by the Windows API. Windows-based programs make extensive use of the Windows API in almost every task. Even if you don't use the API explicitly in your programming, the programming language software will almost always put calls to the Windows API in the generated program to handle various tasks. The Windows API in all encompasses a surprising vast number of topics.

Where is the Windows API?

Almost every function in the Windows API is located in one of the DLL (Dynamic Link Library) files found in the C:\Windows\System directory (or wherever the Windows System directory is). These DLL files "export" functions inside of them -- they allow external programs to use their functions. This design allows any Windows-based program to access any API function relatively easily. The bulk of API functions are found in user32.dll (user interface functions), kernel32.dll (operating system kernel functions), and gdi32.dll (graphics device interface functions), and shell32.dll (Windows shell functions).

What are the Components of the Windows API?

Although so far on this page only the API functions have been refered to, the functions themselves are only one part of the entire API. The following list identifies all the objects which make up the Windows API.

Functions - As already mentioned, the functions make up the core of the Windows API. They are the actual code which accomplish the various tasks handled by the API. They are stored in the DLL files and can be accessed easily from any Windows-based program.
Structures - Structures, combinations of multiple individual variables, are frequently used in the Windows API to store groups of related information. Many API functions require that a structure be passed to them in order to more conveniently transfer a large amount of information without an overly large number of parameters. Although these structures are used by the API functions, your program must properly define them itself.
Named Constants - The Windows API frequently uses otherwise esoteric numeric codes for information. Naming these constants provides a more convenient way to refer to these values in code. Sometimes these constants are used as flags: the data value can be a binary OR of multiple individual flags, allowing one value to store multiple pieces of information. As with structures, the named constants must be explicitly defined in your program.
Callback Functions - Conceptually, a callback function is the reverse of an API function. A callback function is defined completely in your program. This function is then called by an API function routine when it executes its task. Callback functions provide a way to have your program play a critical role in a task. Callback functions are used frequently in enumerations, where all the members of some group are identified one by one; in this case, a callback function is used to allow your program to somehow process each item found belonging to the group.
Messages - In a way, messages are a special type of named constant. While they are also numeric values given names, they behave differently. Messages are sent to objects (especially windows) to tell them to do something. Sending a message does not in itself do anything; rather, it instructs some other object to execute one or more events.

Why Bother?

Granted, using the Windows API to do stuff does have drawbacks. First, API functions are significantly more error-prone than using intrinsic programming language functions. Because the entire API library was created in C++, the information passed to and from the functions must be compliant with C++ syntax, regardless of the programming language you are using. This can cause hard-to-find problems regarding pointers, terminating nulls, and other things you'd rather not have to deal with. Furthermore, API functions are prone to fail spectacularly. Instead of making a nice little error dialog appear, they can easily crash the entire program, forcing it to shut down with a GPF (General Production Fault). And since Visual Basic comes with almost no API documentation whatsoever, you need to find other resources (such as this site!) to learn what functions even exist, let alone how to use them. So why bother at all?

Simple: because API functions are also significantly more powerful than the intrinsic features of pretty much any programming language, especially Visual Basic. For example, in VB you can set the title bar text of any window you created using its .Caption property. But how do you change the text of a window not created by your program? The SetWindowText API function comes in handy, not to mention others. Another example: if you want to use the Open File common dialog box without the API, you need to distribute an OCX library of about 90KB along with your program. Using the GetOpenFileName API function, you can avoid the overhead be accessing what the OCX really serves as a front-end for. And if you want to, say, read and write the Windows registry or use the joysticks connected to the computer, Visual Basic doesn't have the necessary tools. However, even those become possibly using the Windows API!

So, in summary, if Visual Basic or whatever language you use has the ability to perform a certain task, you're better off not using the Windows API for that. You'll have easier requirements and the security of having a more reliable mechanism. But if you want to add more power to your program which VB can't provide, the Windows API is your only way to go. This guide endeavors to provide the Visual Basic user with the information and examples necessary to allow him or her to successfully implement hundreds of API functions (as necessary) in his or her programs.

(no previous page) | Contents of Introduction | Forward to Part 2 >>

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

Last Modified: January 14, 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/part01.html