Microsoft KB Archive/102147

{|
 * width="100%"|

INFO: Class Library Functions to Handle Visual Basic Strings

 * }

Q102147

-

The information in this article applies to:


 * The Microsoft Foundation Classes (MFC), included with:
 * Microsoft Visual C++, versions 1.0, 1.5

-

SUMMARY
The Microsoft Foundation Classes library provides three functions to manipulate Visual Basic strings (otherwise known as HLSTRs). Normally, an application designed with the Microsoft Foundation Classes receives an HLSTR from an event parameter. Technical note 27 provides additional information on receiving these parameters in its section titled "VBX Event-Handling Function Parameters." To view technical notes, choose the MFC Tech Notes icon in the Visual C++ program group in Program Manager.

To make the functions available from any module in your program, add the following statements to a global header file, such as STDAFX.H:

  // Visual Basic string handling declaration section typedef LPVOID HLSTR;

#define ERR   USHORT #define VBAPI FAR PASCAL

LPSTR VBAPI _AfxVBDerefHlstr(HLSTR); ERR  VBAPI _AfxVBGetHlstrLen(HLSTR); ERR  VBAPI _AfxVBSetHlstr(HLSTR FAR *, LPVOID, USHORT); // End of declaration section NOTE: These functions are only available in the static versions of the MFC library. They are not supported in MFC250.DLL.

Visual Basic strings are not maintained as null-terminated sequences of characters. However, you can use the _AfxVBDerefHlstr function to retrieve a pointer to a non-null-terminated string and use _AfxVBGetHlstrLen to determine its length. With this information, you can construct a null-terminated string by copying the string data into a character array and appending a null terminator.

The text below presents the function prototypes and parameter descriptions for each Visual Basic string-handling function that the Microsoft Foundation Classes library provides.

"LPSTR VBAPI _AfxVBDerefHlstr(HLSTR hlstr);" This function returns a pointer to the string data of a Visual Basic string. The returned pointer becomes invalid as soon as the string moves in memory; any call to a function of the Visual Basic application programming interface (API) may have that effect. When the string moves, it must be dereferenced again to obtain a valid pointer.

The length of the string cannot be changed directly. To assign new data to a string or to change its length, use the _AfxVBSetHlstr function. However, _AfxVBDerefHlstr is useful to examine the contents of the string.

The string data is not NULL-terminated. Use the _AfxVBGetHlstrLen function with the _AfxVBDerefHlstr function to determine the length of the string.

  Parameter     Type           Description --  hlstr         HLSTR          Handle to the Visual Basic string.

Comments
This function does not free temporary strings.

Return Value
A far pointer to the string data, or NULL if the string is of zero length. If the string has a length greater than zero, it is not null- terminated and it can contain embedded nulls.

  LPSTR VBAPI  _AfxVBGetHlstrLen(HLSTR hlstr, USHORT FAR * pcbLen); This function returns a pointer to the string data of a Visual Basic string and the length of the string. The returned pointer value becomes invalid as soon as the string moves in memory; any call to a function of the Visual Basic API may have that effect. When the string moves, it must be de-referenced again to obtain a valid pointer.

  Parameter     Type           Description --  hlstr         HLSTR          Handle to the Visual Basic string. pcbLen       USHORT FAR *   A far pointer to an unsigned integer that contains the length of the returned string data.

Comments
This function is identical to _AfxVBDerefHlstr, except that _AfxVBGetHlstrLen also returns the length of the string data through a parameter.

This function does not free temporary strings.

Return Value
A far pointer to the string data, or NULL if the string is of zero length. If the string has a length greater than zero, it is not null- terminated and it can contain embedded nulls:

  ERR VBAPI _AfxVBSetHlstr(HLSTR FAR *phlstr, LPVOID pb, USHORT cbLen); This function assigns a new string value to an existing Visual Basic string (HLSTR). The new string data may be shorter or longer than the existing string. Because the string is managed in the Visual Basic string space, it automatically moves in memory as necessary.

The first argument is not an HLSTR handle, but a pointer to the handle. An HLSTR handle is a user-defined data type that is initialized to 0. If an application passes a pointer to an HLSTR of zero to _AfxVBSetHlstr, the function automatically assigns a new HLSTR handle to the field. Note that this works only with HLSTR handles that are part of a Visual Basic user- defined type. In most cases, the handle itself does not change, only the string data does.

  Parameter     Type           Description --  phlstr        HLSTR far *    Pointer to an HLSTR (a memory location                                that stores a handle to a Visual Basic                                string). pb           LPVOID         Pointer to the string data to assign to                                the Visual Basic string. If this pointer is NULL, then the string is uninitialized and the existing data is not preserved. cbLen        USHORT         Length of the new string in bytes. If                               this argument is 0, the pb argument is                                ignored. If this argument is -1, then pb                               is assumed to be an HLSTR.

Comments
This function can assign one string to another. To do so, set cbLen to -1 and pb to the HLSTR of the source string. If the source HLSTR is a temporary string, this function frees it.

Return Value
Zero, if successful, or an error code.

Additional query words:

Keywords : kb16bitonly kbnokeyword kbMFC kbVC

Issue type : kbinfo

Technology : kbAudDeveloper kbMFC