INFO: Class Library Functions to Handle Visual Basic Strings

ID: Q102147

The information in this article applies to:

The Microsoft Foundation Classes (MFC), included with:
- Microsoft Visual C++ for Windows, 16-bit edition, 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 
Version           : 1.0 1.5
Platform          : WINDOWS 
Issue type        :

Last Reviewed: August 8, 1999