Most programmers are well aware that there is a huge treasure house of software just waiting to be used in your programs in big systems like Windows, Excel, Access, and non-Microsoft sources like Adobe Acrobat. But finding your way to this treasure is like battling the monsters in the latest video game. There are several approaches and we'll consider some of them here! But there is also a surprising diversity of opinion on the best way to do it. We'll consider that here too.

Another classic ... but unfortunately one that has not been updated and is currently out of print ... is Bruce McKinney's Hardcore Visual Basic. Published for VB 5.0, this book is still the best source for information about type libraries and how to build them. Since the only copies you can get now are used (and therefore cheaper), and because the fundamental concepts are still the same, it's probably still worth picking up.

Or maybe not. Bruce himself has decided to abandon his "favorite language" Visual Basic in a tell-all article you can find here. One thing the article does tell is that much of his sophisticated code in the VB 5.0 version of his book was broken pretty severely by VB 6.0. Bruce does right by us because he also lets us download a whole library of fixes for VB 6.0 ... almost as good as a new edition of the book (but not quite - as Bruce tells us in painful detail). The text is still a great read, even if the code doesn't always work. And be sure to read the rebuttal to Bruce's lament, too.

Finally, Microsoft also supplies support for accessing API's, primarily their own. Most of the official Microsoft information is found in application specific Software Development Kits (SDK). Visual Studio does include a lot of support. The good news here is that most of these SDK's can be downloaded for free!

Using an API ...

The two basic approaches to using an API are:

Method 1 - Code a Declare statement in your Visual Basic Source to specify where a DLL function can be found, what types of parameters a DLL expects, and what type of value it returns. Once a function is correctly declared in your VB code, it looks like any other function or subroutine to the VB program. The syntax looks like this:

[Public|Private] Declare Sub globalname Lib libname$ [Alias aliasname$] [(argument list)]

or

[Public|Private] Declare Function globalname Lib libname$ [Alias aliasname$] [(argument list)] [As type]

Here's an actual example of a Declare for a function that returns the Handle of the active window in an application:

Private Declare Function GetActiveWindow Lib "user32" () As Long

The Code -

You can get information about what to put into the Declare statements using Microsoft's API viewer. This is discussed a bit more below.

Here's an example showing how to use the Declare statement. The variable hWnd is the "Window Handle" and can be used to directly address the window. For example, to send it a message or to change properties. In this example, we simply print the Handle to the Immedidate window. If you close and reopen the program, you'll see that hWnd changes since Windows assigns a new number.

Method 2 - Add a type library to your VB application using the VB References menu option. Then the function can be called as though it was part of your project. We'll go into more detail about how to do this below as well.

Let's consider the three recommended sources of information in reverse order. Since you have presumably already paid for your copy of Visual Basic, the tools that come with it are free. One of those is the WIN32API.TXT file and the API Viewer program APILOAD.EXE.

The WIN32API.TXT file holds the "Constants," "Declares" and "Types" for the 32-bit versions of the Windows API functions. There is so much information in this file that early versions of Notepad wouldn't even load it (use Wordpad instead - Windows XP doesn't have this problem). Fortunately, there's a better way! If you select the "Convert Text to Database" option, the program will create a new file called WIN32API.MDB that you can load instead. Do this once and then load the database whenever you want to use the file after that. It's faster and easier.

If you spend just a few seconds browsing WIN32API (or it's database twin), you'll see the hundreds of functions that are yours for the calling. So why wouldn't you use it? Well ... because it may be impressive, but it's often just not correct. Here's what Bruce McKinney says about it, "Unfortunately, WIN32API.TXT has a well-earned reputation for being full of errors." Dan Appleman agrees, "Frankly, Win32API.TXT is not perfectly good. In fact, it's not even close."

So, the idea is good, but you need something better. Let's move up the tree just a bit.

Bruce McKinney's landmark book, Hardcore Visual Basic, came with a lot of software on a CD-ROM, but the crown jewels were two files called WIN.TLB and WINU.TLB. These were the ANSI (Windows 95 for ancient history buffs) and Unicode versions of Bruce's Windows Type Libraries. As Bruce explains it, "Using this type library is equivalent to including WIN32API.TXT in your project."

The good news is that you don't have to buy Bruce's book to get his type library. You can download it now from The Mandelbrot Set, the consulting company that has taken over responsibility.

Microsoft doesn't supply a Win32 type library, so to illustrate using a type library with the Windows GetActiveWindow function, we have to use the WINU.TLB type library available with Bruce McKinney's book.

First ... add the reference. Find the file using the Browse button if necessary.

Then ... include the function in your program. The VB Object Browser tells you everything you need to know.

Both Bruce and The Mandlebrot Set think that you should never use Declare statements (the traditional way to access the functions in an API). Bruce even titles the section in his book where he introduces the issue, "Never Write Another Damn Declare Statement." The Mandlebrot Set states that they specifically disallow the use of the Declare statement in their internal coding standards.

The bad news is that Bruce and The Mandlebrot Set are wrong about never needing anything more than their type libraries. Time to move up the tree once more.

TLIB or Declare?

Dan Appleman also provides a new and improved API text file called API32.TXT to replace the one supplied with Visual Basic. You have to buy the book to get it. Trust me, the book is worth it! And it works just fine with Microsoft's API Viewer program.

Dan Appleman also provides a prebuilt type library on the CD-ROM with his book (called DWAPILIB.TLB, unfortunately, not available for download), but he has this to say about it, "I have very mixed feelings about type libraries for API functions. As you will see, they have a number of advantages and disadvantages. Personally, I prefer to use the Declare statement."

Why does Dan (actually, both Dan's ) feel this way? Consider these points.

Type Libraries are not divisible. When you load a type library, all of the functions and constants become available to your program. While this doesn't load the Declare statements for all those functions into your program, it can make finding the needle you need for your project a little more challenging in the haystack of a big type library like the Win32 API.

You can't add or modify type libraries - especially if the source isn't available. Type libraries are binary files. If a definition in a library isn't there or is (perish the thought) wrong, you can't change it. (You can add your own Declare statement but that defeats the purpose of a type library.) Windows is constantly expanding and gaining more and more functions and not all of them are going to be conveniently in a type library for you to use. And there are rare cases where alternative definitions might be necessary.

And the Declare statement is simply something that VB programmers need to learn to use anyway. Even Bruce admits this and devotes an entire chapter of his book to showing you how. Once you figure them out, it's simply easier and more intuitive to code the appropriate Declare.

Creating your own type library is usually too much trouble for most VB programmers. They have to be created in a special language. The current recommended way to do this is to use IDL - Interface Description Language - and MIDL which comes with C++ or is available with the Microsoft Platform SDK. If you're interested in learning more about how to build your own, Microsoft explains the transition from ODL (which is still recommended in Dan's later book ... a rare miss for Dan) to IDL (recommended in Bruce's earlier book). A good example article about it can be found here.

The Mandlebrot Set, however, punches back with a strong argument in favor of type libraries. Basically, they say that Declare statements are just too dangerous to use in VB programs correctly and that type libraries are necessary to hide the complexity.

What do you think? Should VB programmers always use type libraries and never use Declare statements? Let us know in the message board!