Calling API routines from Access generally takes at least two steps, sometimes three, as follows:
1. |
Declare the function in the Declarations section of a module. |
2. |
Create a wrapper routine to call the routine. |
3. |
Make the call to the API routine. |
Note
A wrapper routine is a VBA routine that sets up the necessary environment for calling the routines, such as needed variables. In some cases, you can skip this step by simply calling the routine directly where it is needed.
The syntax for the last two steps is very much like those when calling VBA routines. The interesting step is the first one, the declaration of an API routine. (You might have noticed that the terms routines and calls have been used rather than subroutines and functions. Like VBA routines, API routines can be subroutines or functions.)
In the Declarations section of a module, you'll have the following syntax for each API call. For a subroutine-type API call, you would have
[Public | Private] Declare Sub Name Lib "LibName" _ [Alias AliasName" [([ArgList])]
For a function-type API call, you would have
[Public | Private] Declare Function Name Lib "LibName" _ [Alias "AliasName"] [([ArgList])] [As Type]
These parameters are used:
Name— The name changes based on whether the routine is being called with an alias. If an alias is used, this should be a name that you make up so that it doesn't conflict with other names and Access commands. If no alias is used, this should be the name of the routine used in the DLL.
LibName— This is the name of one of the DLLs mentioned earlier in the section “Commonly Used DLLs.”
Note
If the DLL being used isn't one of the regular Windows DLLs, you might have to supply the full path and name.
When using a DLL that is located in the System path, you simply have to use the name of the DLL.
AliasName— When you're using an alias, this item should be the actual name of the routine.
ArgList— This is the list of arguments, similar to how Access passes arguments, although the types vary somewhat in certain cases.
Type— This refers to the data type of the return value. This is used for functions only. The data type of the return value can be Byte, Boolean, Integer, Long, Currency, Single, Double, Date, String (variable length only), Object, Variant, a user-defined type, or an object type.
Note
One major difference is that, by default, Access passes variables by reference. Many API calls expect parameters by value instead, so you'll use the ByVal keyword before the argument. For more information on passing arguments, see Chapter 2, “Coding in Access 2000 with VBA.”
Listing 15.1 shows the Declarations section of the module modWindowsAPIUtils, located in Chap15.mdb in the ExamplesChap15 folder on the accompanying CD-ROM.
Notice that each declaration uses the Alias statement and puts wu_ before the routine's name. Again, this is so that no conflicts will occur between existing routines and the new API calls being made.
Note
Also notice that these calls all have an A on the end of them, as in GetComputerNameA. No, it isn't because the developers are from Canada—it's because these routines are the ANSI version. Some calls have W for the Unicode version.
If you examine the first declaration,
Declare Function wu_FindExecutable Lib "shell32.dll" Alias _ "FindExecutableA" (ByVal lpFile As String, _ ByVal lpDirectory As String, ByVal lpResult As String) As Long
you'll notice that it's pretty much a by-the-book declaration. You can break it down as follows:
The routine being called is a function.
The name given to it for this application is wu_FindExecutable. This is so that it won't conflict another one, possibly named FindExecutableA.
Three parameters are being passed by value; all of them are strings.
The return value is a Long.
This routine is classic also in that the return value is actually returning whether it was successful. The actual desired answer—the path and filename of the executable program associated with the given lpFile and lpDirectory—will be passed back in lpResult. This will be shown in greater detail later in “Finding an Executable Application Associated with a File.”
You'll also often see the use of user-defined variables to pass arguments to API calls. The routine found later in the section “Using the Open File Dialog API Call,” uses a structure of type FILE.
18.191.215.117