| Microsoft Office 2000/Visual Basic Programmer's Guide | |
DLL functions don't return strings in the same way that VBA functions do. Because strings are always passed to DLL functions by reference, the DLL function can modify the value of the string argument. Rather than returning a string as the return value for the function, as you would probably do in VBA, a DLL function returns a string into an argument of type String that was passed to the function. The actual return value for the function is often a long integer specifying the number of bytes that were written into the string argument.
A DLL function that takes a string argument gets a pointer to the location of that string in memory. A pointer is just a memory address that indicates where the string is stored. So when you pass a string to a DLL function from VBA, you're passing the DLL function a pointer to your string in memory. The DLL function then modifies the string that's stored at that address.
To call a DLL function that writes to a String variable, you need to take additional steps to format the string properly. First of all, the String variable must be a null-terminated string. A null-terminated string ends in a special null character, which is specified by the VBA constant vbNullChar.
Secondly, a DLL function can't change the size of a string once it has been created. Therefore, you need to make sure that the string that you pass to a function is large enough to hold the entire return value. When you pass a string to a DLL function, you'll usually need to specify the size of the string that you've passed in another argument. Windows keeps track of the length of the string to ensure that it doesn't overwrite any memory that the string is using.
A good way to pass a string to a DLL function is to create a String variable and use the String$ function to fill it with null characters, making it large enough to hold the string that the function returns. For example, the following code fragment creates a string 144 bytes long and filled with null characters:
Dim strTempPath As String
strTempPath = String$(144, vbNullChar)
If you don't know the length of the string when you pass it to the DLL function, you can use the Len function to determine it.
The GetTempPath function, which retrieves the path to the Windows temporary folder, is an example of a DLL function that returns a String value. It takes two arguments — a null-terminated String variable and a numeric variable containing the string's length — and modifies the string so that it contains the path, for example, "C:\Temp\".
Note In order to boot, Windows requires that a temporary folder exist, so this function should always return a path to that folder. If for some reason it doesn't, GetTempPath returns zero.
The following procedure retrieves the path to the Windows temporary folder by calling the GetTempPath function:
Declare Function GetTempPath Lib "kernel32" Alias "GetTempPathA" _
(ByVal nBufferLength As Long, ByVal lpBuffer As String) As Long
Property Get GetTempFolder() As String
' Returns the path to the user's Temp folder. To boot, Windows
' requires that a temporary folder exist, so this should always
' safely return a path to one. Just in case, though, check the
' return value of GetTempPath.
Dim strTempPath As String
Dim lngTempPath As Long
' Fill string with null characters.
strTempPath = String(144, vbNullChar)
' Get length of string.
lngTempPath = Len(strTempPath)
' Call GetTempPath, passing in string length and string.
If (GetTempPath(lngTempPath, strTempPath) > 0) Then
' GetTempPath returns path into string.
' Truncate string at first null character.
GetTempFolder = Left(strTempPath, _
InStr(1, strTempPath, vbNullChar) - 1)
Else
GetTempFolder = ""
End If
End Property
The GetTempFolder property procedure is available in the System class module in System.xls in the ODETools\V9\Samples\OPG\Samples\CH10 subfolder on the Office 2000 Developer CD-ROM.
Figure 10.1 shows how the strTempPath string appears in memory when it is passed to the GetTempPath function, and how it appears after the function call is complete.
Figure 10.1 Returning a String from a DLL Function
Note that the string is filled with null characters when it is passed to the function. The function writes the returned String value, "C:\Temp\", into the first part of the String variable, and the rest remains padded with null characters, which you can then truncate by using the Left function.
The actual return value for the GetTempPath function is the number of characters that have been written into the String variable. If the returned string is "C:\Temp\", the GetTempPath function returns 8.
Note that it's only necessary to pass in a null-terminated string and its size if you're returning a string from a function. If the function does not return a string into a string argument, but instead takes a string that provides information to the function, you can simply pass in a normal VBA String variable.