Sign In
Link to us
Home
1. Introduction
2. Introducing VB
3. Projects
4. Containers
5. Controls
6. Code
7. Forms
8. Debugging Code
9. Error Handling
10. Objects
11. User Controls
12. Data Projects
13. API
 13.1 Calling API Functions
 13.2 API Function Syntax

14. Distribution

Other Resources

Affiliated Links:
www.freefunfings.com


13. API

13.1 Calling API Functions

An API is a method of invoking an external function from Visual Basic. The external functions generally exist in an appropriate "library" of functions, called a "Dynamic Link Library" or "DLL" because you can link your application to it mid-execution without having to explicitly specify that you are going to use it within the project configuration.

A DLL function must be declared to Visual Basic, just like other functions. This allows Visual Basic to anticipate what Data Type the return value and parameters are going to be.

The declaration for an external function must also contain the name of the ".dll" file and the function within it. If the DLL does not exist at the location specified and error will occur. The declaration is made at the top of the module and should be a private declaration. This makes the actual API call a Module-Level method.

Many of these API functions require more than one value to be returned by the function. Normally this is not possible, however, some functions allow you to pass a variable as a ByVal parameter. Since the function then knows the location of the variable within the memory, it can change the contents. An example:

Private Declare Function GetSystemDirectory Lib "kernel32" Alias "GetSystemDirectoryA" _
                   (ByVal lpBuffer As String, ByVal nSize As Long) As Long
This function invokes an API in the DLL called "kernel32.dll". Inside this DLL, Visual Basic expects to find a Long type function called "GetSystemDirectoryA". This function name is an alias for the function name used by Visual Basic, which is "GetSystemDirectory".

The function expects a String type parameter and a Long type parameter, both of which are declared as "ByVal". This means that the function can modify the contents of the variables represented by the parameters.

To call this API, we must declare some variables to be used as the return value and the parameters:

Dim lngRtn As Long
Dim lngSize As Long
Dim strSys As String
lngSize = 255
strSys = String(lngSize, " ")
lngRtn = GetSystemDirectory(strSys, lngSize)
Note:  Notice that the String type variable "strSys" is initialised to be 255 characters long by the String function. This function returns a string of a specified character (in this case a space) repeated a specified number of times. This is done so that the memory occupied by the variable is sufficiently large to hold the new data when the API references the ByVal parameter.
Once the API call is complete, the variable "strSys" would contain the path to the Windows System Directory.

Exercise xxii:
  • Create a new "Standard EXE" project in Visual Basic. Add a FileListBox to the default form and make an application that shows the files in the Windows System Directory. Test your application.

API calls are mainly done for two reasons. Firstly the code is already written and tested, so it is pointless to re-write functions (unless the DLL is under license or system dependant). Secondly, the API functions are pre-compiled and are usually written in C++ making them execute a lot quicker than the equivalent Visual Basic code.

13.2 Determining API Function Syntax

Each of the DLL files on the system may contain many functions that you can use within your application. Some of the DLLs may require licences and even if you have the licence installed, this may not be available when your application is installed onto another machine. For this reason you must be careful about which DLL functions you invoke from your application.

Windows 95/98/NT4 all have similar DLL libraries that contain functions that are regularly used by the system itself and client applications. Some of the more common ones are:

mapi32.dll - MicrosoftT Windows Messaging API functions
winmm.dll - MicrosoftT Windows Multimedia API functions
kernel32.dll - MicrosoftT Windows kernel API functions

In order to find out what functions are contained within these libraries and the calling syntax, VisualStudio incorporates an API Text Viewer.

Exercise:
  • Open the API Text Viewer by selecting Start -> Programs -> Visual Studio 6.0 -> Visual Studio 6.0 Tools -> API Text Viewer
  • When the API Text Viewer loads, select "Load Text File." from the File menu. Navigate to ".Program Files\Microsoft Visual Studio\Common\Tools\WinAPI" folder and open "win32api.txt". This text file describes several of the DLLs that Windows uses.
Note:  Once the API Text Viewer opens this text file, it will be able to give you the correct syntax for each Function, Type and Constant contained in the DLL library associated with the text file.
  • In the search box, type "GetWindowsDirectory"
  • Change the "Declare Scope" option to Private.
  • Double-click the "GetWindowsDirectory" entry in the list of functions. The syntax for declaring this function appears in the box at the bottom. This can be copied and used within your Visual Basic application.
Private Declare Function GetWindowsDirectory Lib "kernel32" Alias "GetWindowsDirectoryA" _
                   (ByVal lpBuffer As String, ByVal nSize As Long) As Long
Note:  Note that the declaration shows that the "GetWindowsDirectory" function exists inside the "kernel32" library.


<<Page 12  :   Top  :   Page 14>>
©vbtraining.co.uk