EXAMINING THE SYNTAX FOR API CALLS

Calling API routines from Access generally takes at least two steps, sometimes three, as follows:

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.”

• 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.

Listing 15.1 shows the Declarations section of the module modWindowsAPIUtils, located in Chap15.mdb in the ExamplesChap15 folder on the accompanying CD-ROM.

Listing 15.1. Chap15.mdb: Sample API Declarations

Option Compare Database
Option Explicit

'-- API Call for finding the associated file
Declare Function wu_FindExecutable Lib "shell32.dll" Alias _
   "FindExecutableA" (ByVal lpFile As String, _
   ByVal lpDirectory As String, ByVal lpResult As String) As Long

'-- API Calls for adding and cancelling network connection
'-- programmatically
Declare Function wu_NetAddConnection Lib "mpr" Alias _
   "WNetAddConnectionA" (ByVal NetPath$, ByVal Password$, _
   ByVal LocalDrive$) As Integer
Declare Function wu_NetCancelConnection Lib "mpr" Alias _
   "WNetCancelConnectionA" (ByVal NetPath$, ByVal FileForce%) _
   As Integer

'-- API Calls for calling the network connect and
'-- disconnect dialogs
Declare Function wu_WNetConnectionDialog Lib "mpr" Alias _
   "WNetConnectionDialog" (ByVal hwnd As Long, ByVal dwType As Long) _
   As Long
Declare Function wu_WNetDisconnectDialog Lib "mpr" Alias _
   "WNetDisconnectDialog" (ByVal hwnd As Long, _
   ByVal dwType As Long) As Long

'-- API Calls for getting the current user and computer names
Declare Function wu_GetUserName Lib "advapi32.dll" Alias _
   "GetUserNameA" (ByVal lpBuffer As String, nSize As Long) _
   As Long
Declare Function wu_GetComputerName Lib "kernel32" Alias _
   "GetComputerNameA" (ByVal lpBuffer As String, nSize As Long) _
   As Long

'-- API Calls for getting the windows, system, and temp directory for
'-- the current computer.
Declare Function wu_GetWindowsDirectory Lib "kernel32" Alias _
   "GetWindowsDirectoryA" (ByVal lpBuffer As String, _
   ByVal nSize As Long) As Long
Declare Function wu_GetSystemDirectory Lib "kernel32" Alias _
   "GetSystemDirectoryA" (ByVal lpBuffer As String, _
   ByVal nSize As Long) As Long
Declare Function wu_GetTempPath Lib "kernel32" Alias _
   "GetTempPathA" (ByVal nBufferLength As Long, _
   ByVal lpBuffer As String) As Long
					

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.

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.