This documentation is archived and is not being maintained.

Programming with CComBSTR

The ATL class CComBSTR provides a wrapper around the BSTR data type. While CComBSTR is a useful tool, there are several situations that require caution.

Conversion Issues

Although several CComBSTR methods will automatically convert an ANSI string argument into Unicode, the methods will always return Unicode format strings. To convert the output string back to ANSI, use an ATL conversion class. For more information on the ATL conversion classes, see ATL and MFC String Conversion Macros.


// Declare a CComBSTR object. Although the argument is ANSI,
// the constructor converts it into UNICODE.
CComBSTR bstrMyString( "Hello World" );
// Convert the string into an ANSI string
CW2CT szMyString( bstrMyString );
// Display the ANSI string
MessageBox( NULL, szMyString, _T("String Test"), MB_OK );

If you are using a string literal to modify a CComBSTR object, use wide character strings. This will reduce unnecessary conversions.


// The following converts the ANSI string to Unicode
CComBSTR bstr("Test");
// The following uses a Unicode string at compile time 
CComBSTR bstr(L"Test");

Scope Issues

As with any well-behaved class, CComBSTR will free its resources when it goes out of scope. If a function returns a pointer to the CComBSTR string, this can cause problems, as the pointer will reference memory that has already been freed. In these cases, use the Copy method, as shown below.


// The wrong way to do it
BSTR * MyBadFunction()
   // Define a pointer to a BSTR
   BSTR * bstrStringPtr;
   // Create the CComBSTR object
   CComBSTR bstrString("Hello World");
   // Convert the string to uppercase
   // Assign the pointer 
   * bstrStringPtr = bstrString;
   // Return the pointer. ** Bad thing to do **
   return bstrStringPtr;
// The correct way to do it
HRESULT MyGoodFunction(/*[out]*/ BSTR* bstrStringPtr)
   // Create the CComBSTR object
   CComBSTR bstrString("Hello World");
   // Convert the string to uppercase
   // Return a copy of the string.
   return bstrString.CopyTo(bstrStringPtr);

Explicitly Freeing the CComBSTR Object

It is possible to explicitly free the string contained in the CComBSTR object before the object goes out scope. If the string is freed, the CComBSTR object is invalid.


// Declare a CComBSTR object
CComBSTR bstrMyString( "Hello World" );
// Free the string explicitly
// The string will be freed a second time
// when the CComBSTR object goes out of scope,
// which is unnecessary.

Using CComBSTR Objects in Loops

As the CComBSTR class allocates a buffer to perform certain operations, such as the += operator or Append method, it is not recommended that you perform string manipulation inside a tight loop. In these situations, CStringT provides better performance.


// This is not an efficient way
// to use a CComBSTR object.
CComBSTR bstrMyString;
while (bstrMyString.Length()<1000)

Memory Leak Issues

Passing the address of an initialized CComBSTR to a function as an [out] parameter causes a memory leak.

In the example below, the string allocated to hold the string "Initialized" is leaked when the function OutString replaces the string.

CComBSTR bstrLeak(L"Initialized");
HRESULT hr = OutString(&bstrLeak);

To avoid the leak, call the Empty method on existing CComBSTR objects before passing the address as an [out] parameter.

Note that the same code would not cause a leak if the function's parameter was [in, out].

See Also

ATL | CStringT | wstring | String Conversion Macros