BSTR Data Type

A BSTR (Basic string or binary string) is a string data type that is used by COM, Automation, and Interop functions. A BSTR is a composite data type that consists of a length prefix, a data string, and a terminator. The following table describes these components.

Item

Description

Length prefix

  • Consists of a four-byte integer.

  • Occurs immediately before the first character of the data string.

  • Contains the number of bytes in the following data string.

  • Does not include the terminator.

Data string

  • On Microsoft Windows, consists of a string of Unicode characters (wide or double-byte characters).

  • On Apple Power Macintosh, consists of a single-byte string.

  • May contain multiple embedded null characters.

Terminator

  • Consists of two null characters (0x00).

A BSTR is a pointer. It is defined in OLEAuto.h as follows:

typedef OLECHAR FAR * BSTR;

The pointer points to the first character of the data string, not to the length prefix.

BSTRs are also referred to as a string of OLECHARs. The OLECHAR data type is defined in WTypes.h as follows:

typedef WCHAR  OLECHAR;

Use the BSTR data type in all interfaces that will be accessed from Visual Basic or from Java applets.

BSTRs are allocated using COM memory allocation functions, so they can be returned from methods without concern for memory allocation.

The following code is incorrect:

BSTR  MyBstr = L"I am a happy BSTR";

This code builds (compiles and links) correctly, but it will not function properly because the string does not have a length prefix. If you use a debugger to examine the memory location of this variable, you will not see a four-byte length prefix preceding the data string.

Instead, use the following code:

BSTR  MyBstr = SysAllocString(L"I am a happy BSTR");

A debugger that examines the memory location of this variable will now reveal a length prefix containing the value 34. This is the expected value for a 17-byte single-character string that is converted to a wide-character string through the inclusion of the "L" string modifier. The debugger will also show a two-byte terminating null character (0x0000) that appears after the data string.

If you pass a simple Unicode (wchar) string as an argument to a COM function that is expecting a BSTR, the COM function will fail.

Show:
© 2014 Microsoft