Programming with CComBSTR (ATL)
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at Programming with CComBSTR (ATL).
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
Scope Issues
Explicitly Freeing the CComBSTR Object
Using CComBSTR Objects in Loops
Memory Leak Issues
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.
Example
// 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.
Example
// The following converts the ANSI string to Unicode
CComBSTR bstr1("Test");
// The following uses a Unicode string at compile time
CComBSTR bstr2(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.
Example
// 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);
}
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.
Example
// 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.
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.
Example
// This is not an efficient way to use a CComBSTR object.
CComBSTR bstrMyString;
HRESULT hr;
while (bstrMyString.Length() < 1000)
hr = bstrMyString.Append(L"*");
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 MyGoodFunction replaces the string.
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].