Returning Strings from DLL Functions

Article
09/14/2006

DLL functions do not return strings in the same way that Microsoft® Visual Basic® for Applications (VBA) functions do. Because strings always are 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 a memory address that indicates where the string is stored. So, when you pass a string to a DLL function from VBA, you are passing the DLL function a pointer to your string in memory. Then, the DLL function modifies the string that is stored at that address.

To call a DLL function that writes to a String variable, you must take additional steps to format the string properly. First, 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.

Second, a DLL function cannot change the size of a string after it has been created. Therefore, you must make sure the string you pass to a function is large enough to hold the entire return value. When you pass a string to a DLL function, you usually must specify the size of the string you have passed in another argument. Microsoft® Windows® keeps track of the length of the string to ensure it does not overwrite any memory 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 returned by the function. 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 do not 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 it contains the path, for example, "C:\Temp\".

Note To boot, Windows requires that a temporary folder exist, so this function always should return a path to that folder. If it does not, 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 following illustration 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:

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 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 It is required only to pass in a null-terminated string and its size if you are 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 pass in a normal VBA String variable.

Returning Strings from DLL Functions

See Also

Additional resources