Wrapping DLL Functions

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

If you call DLL functions frequently, you may want to simplify the process by encapsulating those functions within class modules. By creating a property or method that calls one or more DLL functions, you can work with DLL functions in an object-oriented manner more typical of VBA. And because declaring and calling DLL functions can be a difficult and error-prone experience, packaging calls to DLL functions in reusable objects can save you from having to repeat this experience every time you need to call the API.

When you encapsulate DLL function calls in a class module, you're actually defining a VBA interface for those functions. This is often called "wrapping" a function. You don't change the function itself, but you provide an easier way to call it. Although it can be a little more work to wrap DLL functions, you'll benefit in the long term if you call the functions repeatedly.

To see a simple example of a class that wraps DLL functions, take a look at the System class module in System.xls, available in the ODETools\V9\Samples\OPG\Samples\CH10 subfolder on the Office 2000 Developer CD-ROM. This class wraps some of the functions discussed earlier in this chapter, including, the GetLocalTime, SetLocalTime, and GetTempPath functions. You can create a new instance of the System class and use the resulting object to set or retrieve certain information about the system.

The PropertyGet procedure for each of the Year, Month, Day, Hour, Minute, and Second properties calls the GetLocalTime function, which returns the current value for each portion of the local time into the SYSTEMTIME data structure. To make sure that the value returned by the PropertyGet procedure is current, GetLocalTime is called each time the PropertyGet procedure runs.

The PropertyLet procedure for each property also calls GetLocalTime to ensure that the values in the data structure are current. It then updates the appropriate element of the structure and passes the entire structure to SetLocalTime to change the local system time.

The PropertyGet and PropertyLet procedures for the Hour property are shown in "Passing User-Defined Types" earlier in this chapter.

Once you've created an object-oriented interface for DLL functions, you can create a new instance of the wrapper class and work with its properties and methods. The following example uses the Hour, Minute, and Second properties of the System object to display the local system time in a dialog box.

Sub DisplayLocalSystem()
   Dim sysLocal As System
   Dim strMsg As String
   Dim dteTime  As Date
   
   ' Create new instance of System class.
   Set sysLocal = New System
   
   With sysLocal
      ' Return date value by using Hour, Minute, and
      ' Second properties of System object.
      dteTime = TimeSerial(.Hour, .Minute, .Second)
      strMsg = "The current local system time is: " _
         & CStr(dteTime)
      MsgBox strMsg
   End With
End Sub

This procedure is available in the modDisplaySystem module in System.xls in the ODETools\V9\Samples\OPG\Samples\CH10 subfolder on the Office 2000 Developer CD-ROM.

You can expand the System class to contain other system-related properties and methods. For example, you might add additional properties that call the GetSystemMetrics function with different constants.

For more information about creating custom objects, see Chapter 9, "Custom Classes and Objects."