Home Library Learn Samples Downloads Support Community Forums
This topic has not yet been rated - Rate this topic

Programming with CComBSTR

Visual Studio 2012

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.

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.

C++
Copy 
// 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
CW2A szMyString(bstrMyString);
// Display the ANSI string
MessageBoxA(NULL, szMyString, "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.

C++
Copy 
// The following converts the ANSI string to Unicode
CComBSTR bstr1("Test");
// The following uses a Unicode string at compile time 
CComBSTR bstr2(L"Test");

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.

C++
Copy 
// The wrong way to do it
BSTR * MyBadFunction()
{
   // Create the CComBSTR object
   CComBSTR bstrString(L"Hello World");
   // Convert the string to uppercase
   HRESULT hr;
   hr = bstrString.ToUpper();

   // Return a pointer to the BSTR. ** Bad thing to do ** 
   return &bstrString;
}
// The correct way to do it
HRESULT MyGoodFunction(/*[out]*/ BSTR* bstrStringPtr)
{
   // Create the CComBSTR object
   CComBSTR bstrString(L"Hello World");
   // Convert the string to uppercase
   HRESULT hr;
   hr = bstrString.ToUpper();
   if (hr != S_OK)
       return hr;
   // Return a copy of the string. 
   return bstrString.CopyTo(bstrStringPtr);
}

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.

C++
Copy 
// Declare a CComBSTR object
CComBSTR bstrMyString(L"Hello World");
// Free the string explicitly
::SysFreeString(bstrMyString);
// The string will be freed a second time 
// when the CComBSTR object goes out of scope, 
// which is invalid.

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.

C++
Copy 
// This is not an efficient way to use a CComBSTR object.
CComBSTR bstrMyString;
HRESULT hr;
while (bstrMyString.Length() < 1000)
   hr = bstrMyString.Append(L"*");

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 MyGoodFunction replaces the string.

C++
Copy 
CComBSTR bstrLeak(L"Initialized");
HRESULT hr = MyGoodFunction(&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].

Did you find this helpful?
(1500 characters remaining)
© 2013 Microsoft. All rights reserved.