Win32 API Programming with Visual Basic

2017-07-07 02:10:07

Page 78

6. Strings


		The subject of strings can be quite confusing, but this confusion tends to disappear with some careful attention to detail (as is usually the case). The main problem is that the term string is used in at least two different ways in Visual Basic!


		Just what is a string in Visual Basic? According to the VB documentation, it is:


		A data type consisting of a sequence of contiguous characters that represent the characters themselves rather than their numeric values.


		Huh?


		It seems to me that Microsoft is trying to say that the underlying set for the String data type is the set of finite-length sequences of characters. For Visual Basic, all characters are represented by 2-byte Unicode integers. Put another way, VB uses Unicode to represent the characters in a string. For instance, the ASCII representation for the character h is &H68, so the Unicode representation is &H0068, appearing in memory as 68 00.


		Thus, the string ''help" is represented as:


		00 68 00 65 00 6C 00 70


		Note, however, that because words are written with their bytes reversed in memory, the string "help" appears in memory as:


		68 00 65 00 6C 00 70 00


		This is fine, but it is definitely not how we should think of strings in VB programming. To avoid any possibility of ambiguity, we will refer to this type of object as a Unicode character array which is, after all, precisely what it is! This also helps distinguish it from an ANSI character array, that is, an array of characters represented using single-byte ANSI character codes.

Page 79


		Here is the key to understanding strings: when we write the code:

Dim str As String

str = "help"


		we are not defining a Unicode character array per se. We are defining a member of a data type called BSTR, which is short for Basic String. A BSTR is, in fact, a pointer to a null-terminated Unicode character array that is preceeded by a 4-byte length field. We had better elaborate on this.


	The BSTR


		Actually, the VB string data type defined by:


		Dim str As String


		underwent a radical change between versions 3 and 4 of Visual Basic, due in part to an effort to make the type more compatible with the Win32 operating system.


		Just for comparison (and to show that we are more fortunate now), Figure 6-1 shows the format for the VB string data type under Visual Basic 3, called an HLSTR (High-Level String).

Figure 6-1.

The high-level string format (HLSTR) used by VB3


		The rather complex HLSTR format starts with a pointer to a string descriptor, which contains the 2-byte length of the string along with another pointer to the character array, which is in ANSI format (one byte per character).


		With respect to the Win32 API, this string format is a nightmare. Beginning with Visual Basic 4, the VB string data type changed. The new data type, called a BSTR, is shown in Figure 6-2.


		This data type is actually defined in the OLE 2.0 specifications; that is, it is part of Microsoft's ActiveX specification.


		There are several important things to note about the BSTR data type.

Page 80

Figure 6-2.

A BSTR


		The BSTR is the actual pointer variable. It has size 32 bits, like all pointers, and points to a Unicode character array. Thus, a Unicode character array and a BSTR are not the same thing. It is correct to refer to a BSTR as a string (or VB string) but, unfortunately, the Unicode character array is also often called a string! Hence, we will not refer to a BSTR simply as a string we will refer to it by its unequivocal name BSTR.


		The Unicode character array that is pointed to by a BSTR must be preceded by a 4-byte length field and terminated by a single null 2-byte character (ANSI = 0).


		There may be additional null characters anywhere within the Unicode character array, so we cannot rely on a null character to signal the end of the character array. This is why the length field is vital.


		Again, the pointer points to the beginning of the character array, not to the 4-byte length field that precedes the array. As we will see, this is critical to interpreting a BSTR as a VC++-style string.


		The length field contains the number of bytes (not the number of characters) in the character array, excluding the terminating null bytes. Since the array is Unicode, the character count is one-half the byte count.


		We should emphasize that an embedded null Unicode character is a 16-bit 0, not an 8-bit 0. Watch out for this when testing for null characters in Unicode arrays.


		Note that it is common practice to speak of "the BSTR 'help'" or to say that a BSTR may contain embedded null characters when what is really being referred to is the character array pointed to by the BSTR.


		Because a BSTR may contain embedded null characters, the terminating null is not of much use, at least as far as VB is concerned. However, its presence is extremely important for Win32. The reason is that the Unicode version of a Win32 string (denoted by LPWSTR) is defined as a pointer to a null-terminated Unicode character array (which, by the way, is not allowed to contain embedded null characters).


		This makes it clear why BSTR's are null terminated. A BSTR with no embedded nulls is also an LPWSTR. We will discuss C++ strings in a moment.

Page 81


		Let us emphasize that code such as:

Dim str As String

str = "help"


		means that str is the name of a BSTR, not a Unicode character array. In other words, str is the name of the variable that holds the address xxxx, as shown in Figure 6-2.


		Here is a brief experiment we can do to test the fact that a VB string is a pointer to a character array and not a character array. Consider the following code, which defines a structure whose members are strings:

Private Type utTest

astring As String

bstring As String

End Type

Dim uTest As utTest

Dim s as String

s = "testing"

uTest.astring = "testing"

uTest.bstring = "testing"

Debug.Print Len(s)

Debug.Print Len(uTest)


		The output from this code is:


		In the case of the string variable s, the Len function reports the length of the character array; in this case there are 7 characters in the character array 'testing'. However, in the case of the structure variable uTest, the Len function actually reports the length of the structure (in bytes). The return value of 8 clearly indicates that each of the two BSTRs has length 4. This is because a BSTR is a pointer!


	C-Style LPSTR and LPWSTR Strings


		VC++ and Win32 use the string data types LPSTR and LPWSTR.


		An LPSTR string is defined as a pointer to a null-terminated ANSI character array. However, because the only way that we can tell when an LPSTR string ends is by the location of the terminating null, LPSTRs are not allowed to contain embedded null characters. Similarly, an LPWSTR is a pointer to a null-terminated Unicode character set with no embedded nulls. (The W in LPWSTR stands for Wide, which is Microsoft's way of saying Unicode.) These string data types are pictured in Figure 6-3.

Page 82

Figure 6-3.

LPSTR and LPWSTR data types


		We will also encounter the data types LPCSTR and LPCWSTR. The embedded C stands for constant and simply means that an instance of this data type cannot (and will not) be changed by any API function that uses this type. Otherwise, an LPCSTR is identical to an LPSTR, and, similarly, an LPCWSTR is identical to an LPWSTR.


		Finally, the generic LPTSTR data type is used in conditional compilation, just like the TCHAR data type, to cover both ANSI and Unicode in a single source code. Here are the declarations:

#ifdef UNICODE

typedef LPWSTR LPTSTR; // LPTSTR is synonym for LPWSTR under Unicode

typedef LPCWSTR LPCTSTR; // LPCTSTR is synonym for LPCWSTR under Unicode

#else

typedef LPSTR LPTSTR; // LPTSTR is synonym for LPSTR under ANSI

typedef LPCSTR LPCTSTR; // LPTCSTR is synonym for LPCSTR under ANSI

#endif


		Figure 6-4 summarizes the possibilities.


		Thus, for instance, LPCTSTR is read long pointer to a constant generic string.


	String Terminology


		To avoid any possible confusion, we will use the terms BSTR, Unicode character array, and ANSI character array. When we do use the term string, we will modify it by writing VB string (meaning BSTR) or VC++ string (meaning LP??STR). We will avoid using the term string without some modification.

Page 83

Figure 6-4.

The LP STR mess


		However, in translating VB documentation, you will see the unqualified term string used quite often. It falls to you to determine whether the reference is to a BSTR or a character array.


	Tools for Exploring Strings


		If we are going to do some exploring, then we will need some tools. We have already discussed the CopyMemory API function. Let us take a look at some additional tools for dealing with strings.


		The Visual Basic StrConv Function


		The StrConv function is used to convert character arrays from one format to another. Its syntax is:


		StrConv(string, conversion, LCID)


		where string is a BSTR, conversion is a constant (described later), and LCID is an optional locale identifier (which we will ignore).


		Among the possible constants, and the only ones that interest us, are:


		vbUnicode (which should have been vbToUnicode)


		vbFromUnicode


		These constants convert the character array of the BSTR between Unicode and ANSI.


		But now we have a problem (which really should have been addressed by the official documentation). There is no such thing as an ANSI BSTR. By definition, the character array pointed to by a BSTR is a Unicode array.


		However, we can image what an ANSI BSTR would be just replace the Unicode character array in Figure 6-2 with an ANSI array. We will use the term ABSTR to stand for ANSI BSTR, but you should keep in mind that this term will not be officially recognized outside of this book.

Page 84


		We can now say that there are two legal forms for StrConv:

StrConv(aBSTR, vbFromUnicode) ' returns an ABSTR

StrConv(anABSTR, vbUnicode) ' returns a BSTR


		The irony is that, in the first case, VB doesn't understand the return value of its own function! To see this, consider the following code:

s = "help"

Debug.Print s

Debug.Print StrConv(s, vbFromUnicode)


		The result is:

help


		because VB tries to interpret the ABSTR as a BSTR. Look at the following code:

s = "h" & vbNullChar & "e" & vbNullChar & "l" & vbNullChar & "p" & vbNullChar

Debug.Print s

Debug.Print StrConv(s, vbFromUnicode)


		The output is:

h e l p

help


		Here we have tricked VB by padding the original Unicode character array so that when StrConv does its conversion, the result is an ABSTR that happens to have a legitimate interpretation as a BSTR!


		This shows that the StrConv function doesn't really understand or care about BSTRs and ABSTRs. It assumes that whatever you feed it is a pointer to a character array and it blindly does its conversion on that array. As we will see, many other string functions behave similarly. That is, they can take a BSTR or an ABSTR to them it is just a pointer to some null-terminated array of bytes.


		The Len and LenB Functions


		Visual Basic has two string-length functions: Len and LenB. Each takes a BSTR or ABSTR and returns a long. The following code tells all.

s = "help"

Debug.Print Len(s), LenB(s)

Debug.Print Len(StrConv(s, vbFromUnicode)), LenB(StrConv(s, vbFromUnicode))


		The output is:

4 8

2 4


		showing that Len returns the number of characters and LenB returns the number of bytes in the BSTR.

Page 85


		The Chr, ChrB, and ChrW Functions


		These three functions have different input ranges and produce different outputs. These differences can seem confusing at first you may have to read the definitions a few times:


		Chr takes a long value x in the range 0 to 255 and returns a BSTR of length 1. This one character pointed to by the BSTR has Unicode code equal to x. (In this case, the Unicode and ANSI values are actually equal.) Note that, according to the latest documentation, there is no difference between Chr and Chr$ .


		ChrB takes a long value x in the range 0 to 255 and returns an ABSTR of length 1 (byte). This one byte pointed to by the ABSTR has ANSI code equal to x.


		ChrW takes a long value x in the range 0 to 65535 and returns a BSTR of length 1. This one character pointed to by the BSTR has Unicode code equal to x.


		The Asc, AscB, and AscW Functions


		These functions are the inverses of the Chr functions. For instance, AscB takes a single character (byte) ABSTR and returns a byte equal to the character's ANSI code. To see that the return type is a byte, try running the code:


		Debug.Print VarType(AscB("h")) = vbByte


		(The output is True.) It may appear that AscB will accept a BSTR as input, but in reality, it just takes the first byte in the BSTR.


		The Asc function take a BSTR (but not an ABSTR) and returns an integer equal to the character's Unicode code.


		Null Strings and Null Characters


		To its credit, VB does allow null BSTRs. The code:

Dim s As String

s = vbNullString

Debug.Print VarPtr(s)

Debug.Print StrPtr(s)


		produces the following output (your address may vary, of course):

1243948


		This shows that a null BSTR is simply a pointer whose contents are 0. (We will discuss the meaning of StrPtr in a moment.) In Win32 and VC++, this is called a null pointer. You can probably see the difference between vbNullString and

Page 86


		vbNullChar at this point. vbNullChar is not a pointer it is a Unicode character whose value is 0. Thus, at the bit level, the values vbNullString and vbNullChar are identical. However, they are interpreted differently, so they are in fact different.


		It is also important not to confuse a null BSTR with an empty BSTR, usually denoted by a pair of adjacent quotation marks:

Dim s As String

Dim t As String

s = vbNullString

t = ""


		Unlike a null string, the empty BSTR t is a pointer that points to some nonzero memory address. At that address resides the terminating null character for the empty BSTR, and the preceeding length field also contains a 0.


		VarPtr and StrPtr


		We have discussed the function VarPtr already, but not in connection with strings. The functions VarPtr and StrPtr are not documented by Microsoft, but they can be very useful, so we will use them often, particularly the VarPtr function.


		If var is a variable, we have seen that:


		VarPtr(var)


		is the address of that variable, returned as a long. If str is a BSTR variable, then:


		StrPtr(str)


		gives the contents of the BSTR! These contents are the address of the Unicode character array pointed to by the BSTR.


		Let us elaborate. Figure 6-5 shows a BSTR.

Figure 6-5.

A BSTR


		The code for this figure is simply:

Dim str As String

str = "help"

Page 87


		Note that the variable str is located at address aaaa and the character array begins at address xxxx, which is the contents of the pointer variable str.


		To see that:

VarPtr = aaaa

StrPtr = xxxx


		just run the following code:

Dim lng As Long

Dim i As Integer

Dim s As String

Dim b(1 To 10) As Byte

Dim sp As Long, vp As Long

s = "help"

sp = StrPtr(s)

Debug.Print "StrPtr:" & sp

vp = VarPtr(s)

Debug.Print "VarPtr:" & vp

' Verify that sp = xxxx and vp = aaaa

' by moving the long pointed to by vp (which is xxxx)

' to the variable lng and then comparing it to sp

CopyMemory lng, ByVal vp, 4

Debug.Print lng = sp

' To see that sp contains address of char array,

' copy from that address to a byte array and print

' the byte array. We should get "help".

CopyMemory b(1), ByVal sp, 10

For i = 1 To 10

Debug.Print b(i);


		The output is:

StrPtr:1836612

VarPtr:1243988

True

104 0 101 0 108 0 112 0 0 0


		This shows again that the character array in a BSTR is indeed in Unicode format. Also, by adding the following lines:

Dim ct As Long

CopyMemory ct, ByVal sp - 4, 4

Debug.Print "Length field: " & ct


		just after the lines:

sp = StrPtr(s)

Debug.Print "StrPtr:" & sp

Page 88


		we get the output:


		Length field: 8


		which shows that the length field does indeed hold the byte count and not the character count.


		As mentioned earlier, if you do not like to use undocumented functions (and who can blame you for that?), you can use the function rpiVarPtr in the rpiAPI.dll library on the accompanying CD. You can also simulate StrPtr as follows:

' Simulate StrPtr

Dim lng As Long

CopyMemory lng, ByVal VarPtr(s), 4

' lng = StrPtr(s)


		As we have seen, this code copies the contents of the BSTR pointer, which is the value of StrPtr. to a long variable lng.


	String Conversion by VB


		Now we come to the strange story on how VB handles passing BSTRs to external DLL functions. It doesn't.


		As we have seen, VB uses Unicode internally; that is, BSTRs use the Unicode format. Window NT also uses Unicode as its native character code. However, Windows 9x does not support Unicode (with some exceptions). Let's examine the path that is taken by a BSTR argument to an external DLL function (Win32 API or otherwise).


		In an effort to be compatible with Windows 95, VB always (even when running under Windows NT) creates an ABSTR, converts the BSTR's Unicode character array to ANSI, and places the converted characters in the ABSTR's character array. VB then passes the ABSTR to the external function. As we will see, this is true even when calling the Unicode entry points under Windows NT.


		Preparing the BSTR


		Before sending a BSTR to an external DLL function, VB creates a new ABSTR string at a location different from the original BSTR. It then passes that ABSTR to the DLL function. This duplication/translation process is pictured in Figure 6-6.


		When we first introduced the CopyMemory function, we used it to demonstrate this Unicode-to-ANSI translation process. But let's do that again in a different way. The rpiAPI.dll library includes a function called rpiBSTRtoByteArray, whose purpose is to return the values of VarPtr and StrPtr on the string that is actually passed to a DLL function. The VB declaration is as follows.

Page 89

Figure 6-6.

Translating a BSTR to an ABSTR

Public Declare Function rpiBSTRtoByteArray Lib "???\rpiAPI.dll" ( _

ByRef pBSTR As String, _

ByRef bArray As Byte, _

pVarPtr As Long, _

pStrPtr As Long

) As Long


		For its first parameter, this function takes as input a BSTR, which is passed by reference. Hence, the address of the BSTR is passed, not the address of the character array. (Thus, we are passing a pointer to a pointer to the character array.)


		The second parameter should be set to the first byte of a byte array that the caller must allocate with enough space to accommodate all of the bytes of the BSTR. Failing to do so will definitely crash the application.


		The last two parameters are OUT parameters, meaning that the caller just declares a pair of long variables, which the function will fill in. The pVarPtr variable will be filled by the address of the BSTR, and the pStrPtr will be filled by the contents of the BSTR (which, as we know, is the address of the character array) as the DLL function sees it. Thus, we will be able to get a glimpse of what the DLL is actually passed by VB!


		The function returns the length (in bytes) of the original string. Finally, in order to convince ourselves that everything is working as it should, the function changes the first character of the original string to an X.


		Here is a test run (the function VBGetTarget was discussed in Chapter 3, API Declarations, under the section ''Implementing Indirection in Visual Basic"):

Sub BSTRTest()

Dim i As Integer

Page 90

Dim sString As String

Dim bBuf(1 To 10) As Byte

Dim pVarPtr As Long

Dim pStrPtr As Long

Dim bTarget As Byte

Dim lTarget As Long

sString = "help"

' Print the BSTR's initial address and contents

Debug.Print "VarPtr:" & VarPtr(sString)

Debug.Print "StrPtr:" & StrPtr(sString)

' Call the external function

Debug.Print "Function called. Return value:" & _

rpiBSTRToByteArray(sString, bBuf(1), pVarPtr, pStrPtr

' Print what the DLL sees, which is the temp ABSTR

' Its address and contents are:

Debug.Print 'Address of temp ABSTR as DLL sees it: " & pVarPtr

Debug.Print 'Contents of temp ABSTR as DLL sees it: " & pStrPtr

' Print the buffer pointed to by temp ABSTR

Debug.Print 'Temp character array: ";

For i = 1 To 10

Debug.Print bBuf(i);

Debug.Print

' Now that we have returned from the DLL function call

' check status of the passed string buffer -- it has been deallocated

VBGetTarget lTarget, pVarPtr, 4

Debug.Print 'Contents of temp ABSTR after DLL returns: " & lTarget

' Check the string for altered character

Debug.Print 'BSTR is now: " & sString

End Sub


		Here is the output:

VarPtr:1242736

StrPtr:2307556

Function called. Return value:4

Address of temp ABSTR as DLL sees it: 1242688

Contents of temp ABSTR as DLL sees it: 1850860

Temp character array: 104 101 108 112 0 0 0 0 0 0

Contents of temp ABSTR after DLL returns: 0

BSTR is now: Xelp


		This code first prints the address (VarPtr) and the contents (StrPtr) of the original BSTR as VB sees it. It then calls the function, which fills in the byte buffer and the OUT parameters. Next, the buffer and OUT parameters are printed. The important point to note is that the address and contents of the "string," as returned by the

Page 91


		DLL function, are different than the original values, which indicates that VB has passed a different object to the DLL. In fact, the buffer is in ANSI format; that is, the object is an ABSTR.


		Next, we print the contents of the passed ABSTR, when the DLL has returned. This is 0, indicating that the temporary ABSTR has been deallocated. (It is tempting but not correct to say that the ABSTR is now the null string in fact the ABSTR no longer exists!)


		Finally, note that I am running this code under Windows NT the translation still takes place even though Windows NT supports Unicode.


		The Returned BSTR


		It is not uncommon for a BSTR that is passed to a DLL function to be altered and returned to the caller. In fact, this may be the whole purpose of the function.


		Figure 6-7 shows the situation. After the ABSTR is altered by the DLL function, the translation process is reversed. Thus, the original BSTR str will now point to a Unicode character array with the output of the API function. Note, however, that the character array may not be returned to its original location. For instance, as we will see, the API function GetWindowText seems to move the array. The point is that we cannot rely on the contents of the BSTR to remain unchanged, only its address. This will prove to be an important issue in our discussions later in the chapter.


		What to Call


		Since Windows 9x does not implement Unicode API entry points, for compatibility reasons you will probably want to call only ANSI API entry points in your applications. For instance, you should call SendMessageA, not SendMessageW. (Nonetheless, we will do a Unicode entry point example a little later.)


		The Whole String Trip


		Let's take a look at the entire round trip that a BSTR takes when passed to an external DLL.


		Assume that we call a DLL function that takes a string parameter and modifies that string for return. The CharUpper API function is a good example. This function does an in-place conversion of each character in the string to uppercase. The VB declaration for the ANSI version is as follows.

Declare Function CharUpperA Lib "user32" ( _

ByVal lpsz As String _

) As Long

Page 92

Figure 6-7.

The return translation


		Under Windows 9x


		Under Windows 9x, the following happens to the string argument. Remember that it is the character array pointers that are being passed back and forth, not the actual character arrays:


		The BSTR lpsz is duplicated as an ABSTR by VB, and the duplicate is passed to the function CharUpperA, which treats it as an LPSTR.


		This function processes the LPSTR and passes the result to VB.


		VB translates the LPSTR back to a BSTR.


		Note that since most API functions (in this case CharUpper) treat BSTRs as LPSTRs, that is, they ignore the length field, we cannot be certain that this field will always be accurate. For CharUpper, the length is not changed, so it should remain correct, but other API functions could conceivably change the length of the character array. Unless written specifically for the BSTR format, the function will just null-terminate the new character array, without updating the length field. Thus, we cannot rely on the length field to be valid.


		Under Windows NT


		Under Windows NT, our string argument will go through the following machinations:

Page 93


		1. The string is translated from a BSTR to an ABSTR by VB and passed to the function CharUpperA, which treats it as an LPSTR.


		2. This function translates the LPSTR to an LPWSTR and passes the LPWSTR to the Unicode entry point CharUpperW.


		3. The Unicode function CharUpperW processes the LPWSTR and produces an LPWSTR for output, returning it to CharUpperA.


		4. The function CharUpperA translates the LPWSTR back to an LPSTR and passes it to VB, which thinks of it as an ABSTR.


		5. VB translates the ABSTR back to a BSTR!


		A Unicode Entry Point Example


		Under Windows NT, we can call the Unicode entry points and expect to get something meaningful in return. However, VB still makes the BSTR-to-ABSTR translations, and we must counteract this translation. Here is the ANSI version of a call to CharUpperA:

s = "d:\temp"

Debug.Print s

CharUpperA s

Debug.Print s


		Under both Windows 9x and Windows NT, the outcome is as expected:

d:\temp

D:\TEMP


		Under Windows NT, we might first attempt the Unicode version thusly:

s = "d:\temp"

Debug.Print s

CharUpperW s

Debug.Print s


		but the result is:

d:\temp


		Clearly, something is wrong. Incidentally, here is what the documentation says about errors in the CharUpper function.


		There is no indication of success or failure. Failure is rare. There is no extended error information for this function; do no [sic] call GetLastError.


		Nonetheless, we know that the problem is that VB is making the BSTR-to-ABSTR translation. So let us try the following code:

s = "d:\temp"

Debug.Print s

s = StrConv(s, vbUnicode)

Debug.Print s

Page 94

CharUpperW s

Debug.Print s

s = StrConv(s, vbFromUnicode)

Debug.Print s


		The output is:

d:\temp

d : \ t e m p

D : \ T E M P

D:\TEMP


		What we are doing here is compensating for the shrinking of our BSTR to an ABSTR by expanding it first. Indeed, the first call to the StrConv function simply takes each byte in its operand and expands it to Unicode format. It doesn't know or care that the string is already in Unicode format.


		Consider, for instance, the first Unicode character d. Its Unicode code is 0064 (in hex), which appears in memory as 64 00. Each byte is translated by StrConv to Unicode. which results in 0064 0000 (appearing in memory as 64 00 00 00). The effect is to put a null character between each Unicode character in the original Unicode string.


		Now, in preparation for passing the string to CharUpperW, VB takes this expanded string and converts it from Unicode to ANSI, thus returning it to its original Unicode state. At this point, CharUpperW can make sense of it and do the conversion to uppercase. Once the converting string returns from CharUpperW, VB "translates" the result to Unicode, thus expanding it with embedded null characters. We must convert the result to ANSI to remove the supererogatory padding.


	Passing Strings to the Win32 API


		We can now discuss some of the practical aspects of string passing.


		ByVal Versus ByRef


		Some authors like to say that the ByVal keyword is overloaded for strings, meaning that it takes on a different meaning when applied to strings than when applied to other variables. Frankly, I don't see it. Writing:


		ByVal str As String


		tells VB to pass the contents of the BSTR (actually the ABSTR), which is the pointer to the character array. Thus, ByVal is acting normally it just happens that the content of the BSTR is a pointer to another object, so this simulates a pass by reference. Similarly:


		ByRef str As String


		passes the address of the BSTR, as expected.

Page 95


		IN and OUT String Parameters


		There are many API functions that require and/or return strings. Almost all of these functions deal with C-style strings, that is, LPSTRs or LPWSTRs. Some OLE-related functions do require BSTRs. By way of example, the following function is part of the Microsoft Web Publishing API. Note that it uses BSTRs. (Note also that the declaration is kind enough to tell us which parameters are IN parameters and which are OUT parameters. This is all too rare.)

HRESULT WpPostFile(

[in] LONG hWnd

[in] BSTR bstrLocalPath

[in, out] LONG * plSiteNameBufLen

[in, out] BSTR bstrSiteName

[in, out] LONG * plDestURLBufLen

[in, out] BSTR bstrDestURL

[in] LONG lFlags

[out, retval] LONG * plRetCode

);


		In general, API functions that use strings can do so in three ways:


		They can require a string as input in an IN parameter


		They can return a string as output in an OUT parameter


		They can do both, either in the same parameter or in separate parameters


		To illustrate, Example 6-1 shows three API declarations.


		Example 6-1. Three Example Declarations

// IN parameter example HWND FindWindow( LPCTSTR lpClassName, // pointer to class name LPCTSTR lpWindowName // pointer to window name ); // OUT parameter example int GetWindowText( HWND hWnd, // handle to window or control with text LPTSTR lpString, // address of buffer for text int nMaxCount // maximum number of characters to copy ); // IN/OUT parameter example LPTSTR CharUpper( LPTSTR lpsz // single character or pointer to string );


		The FindWindow function returns a handle to a top-level window whose class name and/or window name matches specified strings. In this case, both parameters are IN parameters.

Page 96


		The GetWindowText function returns the text of a window's title bar in an OUT parameter lpString. It also returns the number of characters in the title as its return value.


		The CharUpper function converts either a string or a single character to uppercase. When the argument is a string, the function converts the characters in the character array in place, that is, the parameter is IN/OUT.


		How shall we convert these function declarations to VB?


		We could simply replace each C-style string with a VB-style:


		ByVal str As String


		declaration, which, as we know, is a BSTR data type. However, there are some caveats.


		Dealing with IN Parameters


		The first declaration in Example 6-1:

HWND FindWindow(

LPCTSTR lpClassName, // pointer to class name

LPCTSTR lpWindowName // pointer to window name

);


		might be translated as follows:

Declare Function FindWindow Lib "user32" Alias "FindWindowA" ( _

ByVal lpClassName As String, _

ByVal lpWindowName As String _

) As Long


		This works just fine. Since the FindWindow function does not alter the contents of the parameters (note the C in LPCTSTR), the BSTRs will be treated by Win32 as LPSTRs, which they are. In general, when dealing with a constant LPSTR, we can use a BSTR.


		We should also note that the FindWindow function allows one (but not both) of its parameters to be set to the null string which, in Win32, is a null pointer (that is, a pointer that contains the value 0). In Win32, this parameter that the programmer chooses not to supply is represented by a null pointer that is, a pointer that contains the value 0. Of course, 0 is not a valid address, so a null pointer is a very special type of pointer and is treated in this way by Win32.


		Fortunately, VB has the vbNullString keyword, which is a null BSTR (and so also a null LPWSTR). It can be used whenever a null string is desired (or required). Actually, this is not as trivial an issue as it might seem at first. Before the

Page 97


		introduction of the vbNullString into Visual Basic (I think with VB 4), we would need to do something like:


		FindWindow(0&, )


		to simulate a null string for the first parameter. The problem is that VB would issue a type mismatch error, because a long 0 is not a string. The solution was to declare three separate aliases just to handle the two extra cases of null parameters. With the introduction of vbNullString, this annoyance went away.


		To illustrate, in order to get the handle of the window with title "Microsoft Word - API.doc," we can write:

Dim sTitle As String

Dim hnd As Long

sTitle = "Microsoft Word - API.doc"

hnd = FindWindow(vbNullString, sTitle)


		or more simply:

Dim hnd As Long

hnd = FindWindow(vbNullString, "Microsoft Word - API.doc")


		Dealing with OUT Parameters


		Now consider the second declaration in Example 6-1:

int GetWindowText(

HWND hWnd, // handle to window or control with text

LPTSTR lpString, // address of buffer for text

int nMaxCount // maximum number of characters to copy

);


		This might be translated to VB as follows:

Declare Function GetWindowText Lib "user32" Alias "GetWindowTextA" ( _

ByVal hwnd As Long, _

ByVal lpString As String, _

ByVal cch As Long _

) As Long


		An HWND is a long value, as is a C-style int (integer). In this case, the string parameter is an OUT parameter, meaning that the function is going to fill this string with something useful in this case, the title of the window whose handle is in the hwnd parameter.


		Here is an example of a call to this function:

Sub GetWindowTitle()

Dim sText As String

Dim hnd As Long

Dim cTitle As Integer

Dim lngS As Long, lngV As Long

Page 98

' Allocate string buffer

sText = String $ (256, vbNullChar)

' Save the BSTR and Unicode character array locations

lngV = VarPtr(sText)

lngS = StrPtr(sText)

' Search for window with a given class

hnd = FindWindow("ThunderRT5Form", vbNullString)

' If window found, get title

If hnd > 0 Then

cTitle = GetWindowText(hnd, sText, 255)

sText = Left $ (sText, cTitle)

Debug.Print sText

' Compare the BSTR and character array locations

' to look for changes

Debug.Print VarPtr(sText), lngV

Debug.Print StrPtr(sText), lngS

Else

Debug.Print "No window with this class name.", vbInformation

End If

End Sub


		The output of one run is:

RunHelp - Unregistered Copy - Monday, December 7, 1998 10:11:53 AM

1243480 1243480

2165764 2012076


		(Don't worry this unregistered program is mine own.)


		We first allocate a string buffer for the window title. We will discuss this important point further in a moment. Then we use FindWindow to search for a window with class name ThunderRT5Form a VB5 runtime form. If such a window is found, its handle is returned in the hnd parameter. We can then call GetWindowText, passing it hnd as well as our text buffer sText and its size. Since the GetWindowText function returns the number of characters placed in the buffer, not including the terminating null, that is, the number of characters in the window title, we can use the Left function to extract just the title from the string buffer.


		Note also that we have saved both the BSTR address (in lngV) and the character array address (in lngS), so that we can compare these values to the same values after calling GetWindowText. Lo and behold, the BSTR has not moved, but its contents have changed, that is, the character array has moved, as we discussed earlier.


		Incidentally, since the returned string is null terminated and contains no embedded nulls, the following function also extracts the portion of the buffer that contains the title. This little utility is generic, and I use it often (in this book as well as in my programs).

Page 99

Public Function Trim0(sName As String) As String

' Right trim string at first null

Dim x As Integer

x = InStr(sName, vbNullChar)

If x > 0 Then Trim0 = Left$ (sName, x - 1) Else Trim0 = sName

End Function


		Getting back to the issue at hand, it is important to understand that, when OUT string parameters are involved, it is almost always our responsibility to set up a string buffer, that is, a BSTR that has enough space allocated to hold the data that will be placed in it by the API function. Most Win32 API functions do not create strings they merely fill strings created by the caller. It is not enough simply to declare:


		Dim sText As String


		We must allocate space, as in:


		sText = String$ (256, vbNullChar)


		Thus, it is important to remember:


		When dealing with OUT string parameters, be sure to allocate a string buffer of sufficient size.


		Note that in some cases, such as GetWindowText, the function provides an IN parameter for specifying the size of the buffer. This is actually a courtesy to us, in the sense that the function agrees not to place more characters in the buffer than we specify as the size of the buffer. (I often give the buffer an extra character that the function doesn't know about. Usually, the function includes the terminating null in its reckoning, but why take chances?)


		Note that there are other cases in which no such courtesy is extended, so we must be careful.


		Consider the case of SendMessage, for example. Here is part of what the Win32 documentation says about the LB_GETTEXT message, which can be used to retrieve the text of an item in a list box.


		An application sends an LB_GETTEXT message to retrieve a string from a listbox.

wParam = (WPARAM) index; // item index [0-based]

lParam = (LPARAM) (LPCTSTR) lpszBuffer; // address of buffer


		[The parameter lpszBuffer is a] pointer to the buffer that will receive the string. The buffer must have sufficient space for the string and a terminating null character. An LB_GETTEXTLEN message can be sent before the LB_GETTEXT message to retrieve the length, in characters, of the string.


		Thus, in this case, there is no IN parameter to act as a safety net. If we fail to allocate sufficient space in the buffer, the function will write over the end of our

Page 100


		buffer, into unknown memory. If we are lucky, this will crash the program. If we are not lucky, it will overwrite some other data, possibly resulting in logical errors in our program, or crashing a client's program!


		However, in this case Windows is not completely devoid of compassion. It does provide the LB_GETTEXTLEN message for us to use to first retrieve the length of the item in question. With this value, we can allocate a sufficiently capacious buffer. Example 6-2 shows some sample code. This code extracts the items from a listbox (which might belong to some other application) and places them in our listbox lstMain. We will expand this example considerably in Chapter 16, Windows Messages. Note the use of two different forms of the SendMessage function.


		Example 6-2. Using LB_GETTEXT

Public Sub ExtractFromListBox(hControl As Long)

Dim cItems As Integer

Dim i As Integer

Dim sBuf As String

Dim cBuf As Long

Dim lResp As Long

' Get item count from control

cItems = SendMessageByLong(hControl, LB_GETCOUNT, 0&, 0&)

If cItems <= 0 Then Exit Sub

' Put items into list box

For i = 0 To cItems - 1

' Get length of item

cBuf = SendMessageByString(hControl, LB_GETTEXTLEN, CLng(i), vbNullString)

' Allocate buffer to hold item

sBuf = String$ (cBuf + 1, )

' Send message to get item

lResp = SendMessageByString(hControl, LB_GETTEXT, CLng(i), sBuf)

' Add item to local list box

If lResp > 0 Then

Form1.lstMain.AddItem Left$ (sBuf, lResp)

End If

Next i

Form1.lstMain.Refresh

End Sub

Page 101


		An IN/OUT Parameter Example Watching Out for As Any


		Consider now the third and final function in Example 6-1:

PTSTR CharUpper(

LPTSTR lpsz // single character or pointer to string

);


		One problem here is that, despite the declaration of lpsz as an LPTSTR, the function allows the parameter to be filled with a non-LPTSTR. To wit, the documentation states that the lpsz parameter is a:


		Pointer to a null-terminated string or specifies a single character. If the high-order word of this parameter is zero, the low-order word must contain a single character to be converted.


		For use with string input, we can translate this into VB as:

Declare Function CharUpperForString Lib "user32" Alias "CharUpperA" ( _

ByVal lpsz As String _

) As Long


		This will generally work, as in:

' Convert string

str = "help"

Debug.Print StrPtr(str)

Debug.Print CharUpperForString(str)

Debug.Print str


		whose output is:

1896580

1980916

HELP


		Let us pause for a moment to inspect this output. The CharUpper documentation also states:


		If the operand is a character string, the function returns a pointer to the converted string. Since the string is converted in place, the return value is equal to lpsz.


		On the other hand, the two addresses StrPtr(s) (which is the address of the character array) and CharUpper(s) seem to be different. But remember the BSTR-to-ABSTR translation issue. Our string str undergoes a translation to a temporary ABSTR string at another location. This string is passed to the CharUpper function, which then changes the string (uppercases it) and also returns the location of the ABSTR string. Now, VB translates the ABSTR back to our BSTR, but it knows nothing about the fact that the return value represents the location of the temporary ABSTR, so it returns the address of that string!

Page 102


		We can confirm this further by calling the Unicode entry point, just as we did in an earlier example. The following declaration and code:

Declare Function CharUpperWide Lib "user32" Alias "CharUpperW" ( _

ByVal lpsz As Long _

) As Long

' Construct an LPSTR

s = "help"

lng = StrPtr(s)

Debug.Print lng

Debug.Print CharUpperWide(lng)

Debug.Print s


		returns:

1980916

HELP


		Now the two addresses are the same, since no translation occurs!


		For dealing with characters, we can make the following declaration:

Declare Function CharUpperForChar Lib "user32" Alias "CharUpperA" ( _

ByVal lpsz As Long _

) As Long


		For instance, calling:


		Debug.Print Chr(CharUpperForChar(CLng(Asc("a"))))


		returns an uppercase A.


		You might think we could combine the two declarations by using As Any.

Declare Function CharUpperAsAny Lib "user32" Alias "CharUpperA" ( _

ByVal lpsz As Any _

) As Long


		The following code works:

s = "help"

Debug.Print StrPtr(s)

Debug.Print CharUpperAsAny(s)

Debug.Print s


		as does:


		Debug.Print Chr(CharUpperAsAny(CLng(Asc("a"))))


		and:


		Debug.Print Chr(CharUpperAsAny(97&))


		(which returns the uppercase letter A.) However, the following code crashes my computer:


		Debug.Print CharUpperAsAny(&H11000)

Page 103


		The problem is that the CharUpper function sees that the upper word of &H11000 is nonzero, so it assumes that the value is an address. But this is fatal. Who knows what is at address &H1100? In this case, it is protected memory.


		What Happened to My Pointer?


		There is another, much more insidious problem that can arise in connection with passing strings to API functions. As we can see from the CharUpper case, the API occasionally uses a single parameter to hold multiple data types (at different times, of course). Imagine the following hypothetical circumstance.


		A certain API function has declaration:

LPTSTR WatchOut(

int nFlags // flags

LPTSTR lpsz // pointer to string or length as a long

);


		The documentation says that if nFlags has value WO_TEXT (a symbolic constant defined somewhere), then lpsz will receive an LPTSTR string (pointer to a character array), but if nFlags has value WO_LENGTH, then lpsz gets the length of the string, as a long.


		Now, if we make the VB declaration:

Declare Function WatchOut Lib "whatever" ( _

ByVal nFlags As Integer

ByVal lpsz As String _

) As Long


		we can get into real trouble. In particular, if we set nFlags equal to WO_LENGTH, then the following events take place under Windows 9x:


		1. We create an initial BSTR string buffer for lpsz (see Figure 6-8), say:

Dim str As String

str = String$ (256, vbNullChar)

Figure 6-8

The initial ABSTR


		2. VB creates a temporary ABSTR to pass to WatchOut, as shown in Figure 6-9.

Page 104

Figure 6-9

The temporary ABSTR


		3. As Figure 6-10 shows, because nFlags = WO_LENGTH, WatchOut changes the pointer, not the character array!

Figure 6-10

The resulting broken pointer


		4. VB tries to translate what it thinks is an ANSI character array at address zzzz of length ????. This is a disaster.


		Under Windows NT, the WatchOut function changes the original BSTR pointer (instead of an ANSI copy), but this will have the same disastrous effects. Note that even if we somehow are unlucky enough to escape a crash when VB tries to translate the fraudulent ABSTR, the result will be garbage, the program may crash after we send it to our customers, and there is still the matter of the dangling string, whose memory will not be recovered until the program terminates. This is called a memory leak.


		The problem can be summarized quite simply: occasionally an API function will change a string pointer (not the string itself) to a numeric value. But VB still thinks it has a pointer. This spells disaster. In addition, testing to see whether the contents of the BSTR pointer variable have changed doesn't solve the problem, because as we have seen (Figure 6-8), VB sometimes changes the pointer to point to a legitimate character array!


		As it happens, the situation described earlier can occur. Here is an important example, which we will play with at the end of the chapter.

Page 105


		The GetMenuItemInfo function retrieves information about a Windows menu item. Its declaration is:

BOOL GetMenuItemInfo(

HMENU hMenu, // handle of menu

unit uItem, // indicates which item to look at

BOOL fByPosition, // used with uItem

MENUITEMINFO *lpmii // pointer to structure (see discussion)

);


		where, in particular, the parameter lpmii is a pointer to a MENUITEMINFO structure that will be filled in by GetMenuItemInfo. This structure is:

typedef struct tagMENUITEMINFO {

UINT cbSize;

UINT fMask;

UINT fType;

UINT fState;

UINT wID;

HMENU hSubMenu;

HBITMAP hbmpChecked;

HBITMAP hbmpUnchecked;

DWORD dwItemData;

LPTSTR dwTypeData;

UINT cch;

}


		Note that the penultimate member is an LPTSTR.


		Now, the rpiAPIData application on the accompanying CD will automatically translate this to a VB user-defined type, replacing all C data types in this case by VB longs:

Public Type MENUITEMINFO cbSize As Long '//UINT fMask As Long '//UINT fType As Long '//UINT fState As Long '//UINT wID As Long '//UINT hSubMenu As Long '//HMENU hbmpChecked As Long '//HBITMAP hbmpUnchecked As Long '//HBITMAP dwItemData As Long '//DWORD dwTypeData As Long '//LPTSTR cch As Long '//UINT End Type


		Suppose instead that the LPTSTR was translated into a VB string:


		dwTypeData As String '//LPTSTR


		According to the documentation for MENUITEMINFO, if we set the fMask parameter to MIIM_TYPE, allocate a suitable string buffer in dwTypeData, and place its length in cch, then the GetMenuItemInfo function will retrieve the type of the menu item into fType (and adjust the value of cch). If this type is MFT_TEXT, then

Page 106


		the string buffer will be filled with the text of that menu item. However, and this is the problem, if the type is MFT_BITMAP, then the low-order word of dwTypeData gets the bitmap's handle (and cch is ignored).


		Thus, GetMenuItemInfo may change dwDataType from an LPTSTR to a bitmap handle! This is exactly the problem we described earlier. We will consider an actual example of this later in the chapter. Keep in mind also that even if the type is MFT_TEXT, the dwDataType pointer may be changed to point to a different character buffer.


		So if we shouldn't use a string variable for dwDataType, what should we do?


		The answer is that we should create our own character array by declaring a byte array and pass a pointer to that array. In other words, we create our own LPSTR. The VB will not try to interpret it as a VB string.


		This even solves the orphaned array problem, for if the API function changes our LPSTR to a numeric value (like a bitmap handle), we still retain a reference to the byte array (we had to create it somehow), so we can deallocate the memory ourselves (or it will be allocated when the byte array variable goes out of scope).


		Before getting into a discussion of byte arrays and looking at an example, let us summarize:


		Occasionally an API function will change an LPSTR to a numeric value. But VB will still think it has a string. This spells disaster. Moreover, testing to see whether the contents of the BSTR pointer variable have changed doesn't help because VB sometimes changes the original BSTR to point to a legitimate character array. Hence, if there is a chance that this might happen, you should create your own LPSTR using a byte array and use it in place of the BSTR. For safety, you may want to do this routinely when the string is embedded within a structure.


		The last point made in the caveat is worth elaborating. Oftentimes an API function parameter refers to a structure, whose members may be other structures, whose members may, in turn, be other structures. This structure nesting can get quite involved. We will see an example when we create our DLL Export Table application. This makes it very difficult to keep track of what the API function might be doing to all of the structure members. The safest thing to do is to always use pointers to byte arrays (that is, LPSTRs) and avoid BSTRs completely when dealing with strings embedded in structures.


	Strings and Byte Arrays


		Of course, a byte array is just an array whose members have type byte, for instance:


		Dim b(1 to 100) As Byte

Page 107


		To get a pointer to this byte array, we can use VarPtr:

Dim lpsz As Long

lpsz = VarPtr(b(1)) ' or rpiVarPtr(b(1))


		(Even though it doesn't seem so, the letters lpsz stand for long pointer to null-terminated string.) Note that the address of the first member of the array is the address of the array.


		Remembering that an LPSTR is a pointer to a null-terminated character array, we should initialize the array to nulls:

For i = 1 To 100

b(i) = 0


		(It is true that VB does its own initialization, but it is not good programming practice to rely on this.)


		Translating Between Byte Arrays and BSTRs


		To copy a BSTR:


		Dim s As String


		to a byte array, we can proceed in a couple of different ways. For a strictly VB solution, we have:

s = "help"

Dim b(1 To 8) As Byte

For i = 1 To 8

b(i) = AscB(MidB(s, i))


		Another approach is:

s = "help"

Dim b(1 To 8) As Byte

CopyMemory b(1), ByVal StrPtr(s), LenB(s)


		Note that (in both cases) we get:


		104 0 101 0 108 0 112 0


		showing that the bytes are reversed in each Unicode integer.


		In the other direction, to copy a byte array into a BSTR, VB gives us some help. If b is a Unicode byte array, we can just write:

Dim t As String

t = b


		For an ANSI byte array b, we write:

Dim t As String

t = StrConv(b, vbUnicode)

Page 108


		Note, however, that the StrConv function does not recognize a null terminator in the byte array it will translate the entire array. Any nulls that are encountered in the array become embedded nulls in the BSTR.


		Translating Between BSTRs and LPTSTRs


		Let us consider how to translate back and forth between BSTRs and LPTSTRs.


		From BSTR to LPWSTR


		Getting a BSTR into a Unicode byte array is conceptually easy, because the character array of the BSTR is a Unicode byte array, so all we need to do is copy the bytes one by one. Here is a function to translate BSTRs to LPWSTRs:

Function BSTRtoLPWSTR(sBSTR As String, b() As Byte, lpwsz As Long) As Long

' Input: a nonempty BSTR string

' Input: **undimensioned** byte array b()

' Output: Fills byte array b() with Unicode char string from sBSTR

' Output: Fills lpwsz with a pointer to b() array

' Returns byte count, not including terminating 2-byte Unicode null character

' Original BSTR is not affected

Dim cBytes As Long

cBytes = LenB(sBSTR)

' ReDim array, with space for terminating null

ReDim b(1 To cBytes + 2) As Byte

' Point to BSTR char array

lpwsz = StrPtr(sBSTR)

' Copy the array

CopyMemory b(1), ByVal lpwsz, cBytes + 2

' Point lpsz to new array

lpwsz = VarPtr(b(1))

' Return byte count

BSTRtoLPWSTR = cBytes

End Function


		This function takes a BSTR, an undimensioned byte array, and a long variable lng and converts the long to an LPWSTR. It returns the byte count as the return value of the function. Here is an example:

Dim b() As Byte

Dim lpsz As Long, lng As Long

lng = BSTRToLPWSTR("here", b, lpsz)

Page 109


		It might have occurred to you to simply copy the contents of the BSTR to the contents of lpsz:


		lpsz = StrPtr(sBSTR)


		The problem is that now we have two pointers to the same character array a dangerous situation because VB does not realize this and might deallocate the array.


		From BSTR to LPSTR


		The function to convert a BSTR to an LPSTR is similar, but requires a translation from Unicode to ANSI first:

Function BSTRtoLPWSTR(sBSTR As String, b() As Byte, lpsz As Long) As Long

' Input: a nonempty BSTR string

' Input: **undimensioned** byte array b()

' Output: Fills byte array b() with ANSI char string

' Output: Fills lpsz with a pointer to b() array

' Returns byte count, not including terminating null

' Original BSTR is not affected

Dim cBytes As Long

Dim sABSTR As String

cBytes = LenB(sBSTR)

' ReDim array, with space for terminating null

ReDim b(1 To cBytes + 2) As Byte

' Convert to ANSI

sABSTR = StrConv(sBSTR, vbFromUnicode)

' Point to BSTR char array

lpsz = StrPtr(sABSTR)

' Copy the array

CopyMemory b(1), ByVal lpsz, cBytes + 2

' Point lpsz to new array

lpsz = VarPtr(b(1))

' Return byte count

BSTRtoLPSTR = cBytes

End Function


		From LPWSTR to BSTR


		On return from an API call, you may have an LPWSTR, that is, a pointer to a null-terminated Unicode character array. Visual Basic makes it easy to get a BSTR from a byte array just make an assignment using the equal sign. However, VB doesn't know how to handle a pointer to a byte array.

Page 110


		Here is a little utility:

Function LPWSTRtoBSTR(ByVal lpwsz As Long) As String

' Input: a valid LPWSTR pointer lpwsz

' Return: a sBSTR with the same character array

Dim cChars As Long

' Get number of characters in lpwsz

cChars = lstrlenW(lpwsz)

' Initialize string

LPWSTRtoBSTR = String$ (cChars, 0)

' Copy string

CopyMemory ByVal StrPtr(LPWSTRtoBSTR), ByVal lpwsz, cChars * 2

End Function


		From LPSTR to BSTR


		We can modify the previous utility to return a BSTR from an LPSTR as follows (recall that Trim0 just truncates a string at the first null character)

Function LPSTRtoBSTR(ByVal lpsz As Long) As String

' Input: a valid LPSTR pointer lpsz

' Output: a sBSTR with the same character array

Dim cChars As Long

' Get number of characters in lpsz

cChars = lstrlenA(lpsz)

' Initialize string

LPSTRtoBSTR = String$ (cChars, 0)

' Copy string

CopyMemory ByVal StrPtr(LPSTRtoBSTR), ByVal lpsz, cChars

' Convert to Unicode

LPSTRtoBSTR = Trim0(StrConv(LPSTRtoBSTR, vbUnicode))

End Function


		Example: Using Byte Arrays


		Let us demonstrate the use of byte arrays with a simple example using CharUpper. We have seen that this function is declared as:

LPTSTR CharUpper(

LPTSTR lpsz // single character or pointer to string

);

Page 111


		This leads to two reasonable translations into VB:

Declare Function CharUpperByBSTR Lib "user32" Alias "CharUpperA" ( _

ByVal s As String _

) As Long


		Or:

Declare Function CharUpperByLPSTR Lib "user32" Alias "CharUpperA" ( _

ByVal lpsz As Long _

) As Long


		We have seen the first form in action, so let us try the second form.


		The following code first converts a BSTR to an LPSTR. Note that we should not convert to LPWSTR, since LPWSTRs are passed to CharUpperA without translation by VB; and if we passed an LPWSTR, then as soon as CharUpperA encountered the null byte that is part of the first Unicode character in the LPWSTR, it would think the string had ended. Thus, it would capitalize only the first character in the string.


		The LPSTR is then passed to CharUpperA, which converts it to uppercase. Having saved the LPSTR pointer, we can check to see if it has been changed. If not, we translate the LPSTR back to a BSTR and print it. If the pointer is changed, then we must deallocate the byte array ourselves (or just let the array variable pass out of scope).


		Of course, in this simple example, the pointer should not be changed by CharUpper. Nevertheless, this same procedure will deal with API functions that may change the pointer:

Public Sub CharUpperText

Dim lpsz As Long

Dim lpszOrg As Long

Dim sBSTR As String

Dim b() As Byte

sBSTR = "help"

' Convert BSTR to LPSTR.

BSTRtoLPSTR sBSTR, b, lpsz

' Save LPSTR to check for modification by API function

lpszOrg = lpsz

' Convert to upper case

CharUpperAsLPWSTR lpsz

' If pointer not modified, then convert back to BSTR

' and print

If lpszOrg = lpsz Then

Page 112

Debug.Print LPSTRtoBSTR(lpsz)

Else

Erase b

' Use new value of lpsz if desired

End If

End Sub


		Example: Windows Menus


		Let us turn to the example involving GetMenuItemInfo that we promised earlier. Recall that the GetMenuItemInfo function retrieves information about a Windows menu item. Its VB declaration is:

Declare Function GetMenuItemInfo Lib "user32" Alias "GetMenuItemInfoA" ( _

ByVal hMenu As Long, _

ByVal uItem As Long, _

ByVal lByPos As Long, _

ByRef lpMenuItemInfo As MENUITEMINFO _

) As Long


		where, in particular, the parameter lpmii is a pointer to a MENUITEMINFO structure that will be filled in by GetMenuItemInfo. This structure is:

Public Type MENUITEMINFO

cbSize As Long

fMask As Long

fType As Long

fState As Long

wID As Long

hSubMenu As Long

hbmpChecked As Long

hbmpUnchecked As Long

dwItemData As Long

dwTypeData As Long

cch As Long

End Type


		According to the documentation, if we set the fMask parameter to MIIM_TYPE, allocate a suitable string buffer in dwTypeData, and place its length in cch, then the GetMenuItemInfo function will retrieve the type of the menu item into fType. If this type is MFT_TEXT, then the string buffer will be filled with the text of that menu item. However, and this is the problem, if the type is MFT_BITMAP, then the low-order word of dwTypeData gets the bitmap's handle. Thus, in this case, GetMenuItemInfo will change dwTypeData from an LPTSTR to a bitmap handle!


		Figure 6-11 shows a menu with a bitmap. We will discuss how to create such a menu in VB using the Win32 API in Chapter 21, Bitmaps.


		Example 6-3 shows the code used to get the text for each of the items in this menu.

Page 113

Figure 6-11.

A menu with a bitmap


		Example 6-3. Getting Menu Text

Public Sub GetMenuInfoExample

Const MIIM_TYPE = &H10 ' from WINUSER.H

Dim uMenuItemInfo As MENUITEMINFO

Dim bBuf (1 To 50) As Byte

Dim sText As String

' Initialize structure

uMenuItemInfo.cbSize = LenB(uMenuItemInfo)

uMenuItemInfo.fMask = MIIM_TYPE

uMenuItemInfo.dwTypeData = VarPtr(bBuf(1))

uMenuItemInfo.cch = 49

' Get menu text

For i = 0 To 2

' Must reset count each time

uMenuItemInfo.cch = 49

' Get TypeData before

Debug.Print Before: & uMenuItemInfo.dwTypeData

' Call API

lng = GetMenuItemInfo(hSubMenu, CLng(i), -1, uMenuItemInfo)

' Get TypeData after

Debug.Print After: & uMenuItemInfo.dwTypeData

' Print text -- CAREFUL HERE

' sText = StrConv(bBuf, vbUnicode)

' Debug.Print sText

End Sub


		Here is what happens as this code executes.


		The first loop (i = 0) presents no problems, and the output is:

Before:1479560

After:1479560

Page 114


		Observe that the buffer pointer had not changed. Hence, the commented code that prints the menu text would run without error.


		The second loop also runs without error (as long as the statements involving sText are commented out). The output, however, is:

Before:1479560

After:3137668829


		As the documentation suggests, GetMenuItemInfo returns the bitmap's handle in uMenuItemInfo.dwTypeData. Thus, we have lost the pointer to the buffer sBuf. On the third loop, the program will crash, because the third call to GetMenuItemInfo will try to write the menu text for the third item to an imaginary buffer at address 3137668829 = &Hbb0506dd. If this memory is protected (as it probably is), you will get a message similar to the one I got in Figure 6-12.

Figure 6-12.

Whoops


		Note that if we uncomment the lines of code that print the menu text, the code will probably crash when we come to these lines during the second loop.


		To fix this code, we need to pay attention to when the pointer changes and correct the problem, as in Example 6-4.


		Example 6-4. A Corrected Version of Example 6-3

Public Sub GetMenuInfoExample

Dim uMenuItemInfo As utMENUITEMINFO

Dim bBuf (1 To 50) As Byte

Dim sText As String

Dim lPointer As Long

' Initialize structure

uMenuItemInfo.cbSize = LenB(uMenuItemInfo)

uMenuItemInfo.fMask = MIIM_TYPE

uMenuItemInfo.dwTypeData = VarPtr(bBuf(1))

uMenuItemInfo.cch = 49

Page 115


		Example 6-4. A Corrected Version of Example 6-3 (continued)

' Get menu text

For i = 0 To 2

' Must reset count each time

uMenuItemInfo.cch = 49

' Save buffer pointer

lPointer = uMenuItemInfo.dwTypeData

Debug.Print Before: & uMenuItemInfo.dwTypeData

' Call API

lng = GetMenuItemInfo(hSubMenu, CLng(i), -1, uMenuItemInfo)

Debug.Print After: & uMenuItemInfo.dwTypeData

' Check for pointer change

If lPointer <> uMenuItemInfo.dwTypeData Then

Debug.Print Bitmap!

' Restore pointer

uMenuItemInfo.dwTypeData = lPointer

Else

' Print text

sText = StrConv(bBuf, vbUnicode)

Debug.Print sText

End If

End Sub


		The output is:

Before:1760168

After:1760168

Test1

Before:1760168

After:1443168935

Bitmap!

Before:1760168

After:1760168

Test3


		Note that if we had declared uMenuItemInfo.dwTypeData of type String, then as soon as GetMenuItemInfo changed the pointer to the bitmap handle, VB would think it had a character array at that location. We can't even watch out for this and reset the pointer, because the change might have been legitimate.


		The previous discussion and the previous example have shown that we need to be very careful about BSTRs. In short, there are two issues that must be addressed:


		A BSTR undergoes a BSTR-to-ABSTR translation when passed to an external function.

Page 116


		A BSTR may have its value changed to a non-BSTR value (such as a handle or length) by an external function.


		Note that these issues must be addressed even when a BSTR is embedded in a structure.


		In any case, the translation issue is generally not a problem, since VB does the reverse translation on the return value. However, the other issue can be a fatal problem. The only way to avoid it completely is to manually replace any BSTRs by LPSTRs, using a byte array.


		Getting the Address of a Variable of User-Defined Type


		An API programmer often needs to get the address of a variable of user-defined type. Consider, for example, the structure:

Type utExample

sString As String

iInteger As Integer

End Type

Dim uEx As utExample


		Suppose we want to find the address of the variable uEx. First, note that the address of a structure variable is the same as the address of its first member.


		Now consider the following code:

Debug.Print VarPtr(uEx)

Debug.Print VarPtr(uEx.sString)

Debug.Print VarPtr(uEx.iInteger)

Debug.Print

Debug.Print rpiVarPtr(uEx)

Debug.Print rpiVarPtr(uEx.sString)

Debug.Print rpiVarPtr(uEx.iInteger)


		whose output is as follows.

1243836

1243840

1243824

1243820

1243840


		As you can see, VarPtr reports the address as you would expect: the address of uEx is the same as the address of uEx.aString, and the address of uEx. iInteger is 4 bytes larger, to account for the 4-byte BSTR.

Page 117


		On the other hand, the rpiVarPtr is susceptible to BSTR-to-ABSTR translation, which occurs on the member of the structure that is a BSTR.


		The relationship between the first and second address in the second group may look strange until we remember that each call to rpiVarPtr produces a translation, so we cannot compare addresses from two separate calls, both of which involve translations!


		On the other hand, the third address is the address of the original integer member. There is no translation in the call:


		Debug.Print rpiVarPtr(uEx.iInteger)


		because there are no BSTR parameters. Thus, we can use an external function such as rpiVarPtr to compute the address of a structure provided the structure has at least one non-BSTR parameter. In this event, we get the address of one such parameter and count backwards to the beginning of the structure

Категории