INFO: Class Library Functions to Handle Visual Basic Strings

• The Microsoft Foundation Classes (MFC) included with:

      - Microsoft Visual C++ for Windows, 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

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);

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

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);

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