Allocating and Releasing Memory for a BSTR

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 Allocating and Releasing Memory for a BSTR.

When you create BSTRs and pass them between COM objects, you must take care in treating the memory they use in order to avoid memory leaks. When a BSTR stays within an interface, you must free its memory when you are done with it. However, when a BSTR passes out of an interface, the receiving object takes responsibility for its memory management.

In general, the rules for allocating and releasing memory allocated for BSTRs are as follows:

• When you call into a function that expects a BSTR argument, you must allocate the memory for the BSTR before the call and release it afterwards. For example:

  HRESULT CMyWebBrowser::put_StatusText(BSTR bstr)
  

        // shows using the Win32 function 
        // to allocate memory for the string: 
        BSTR bstrStatus = ::SysAllocString(L"Some text");
        if (bstrStatus != NULL)
        {
           pBrowser->put_StatusText(bstrStatus);
           // Free the string:
           ::SysFreeString(bstrStatus);
        }
  

• When you call into a function that returns a BSTR, you must free the string yourself. For example:

  HRESULT CMyWebBrowser::get_StatusText(BSTR* pbstr)
  

        BSTR bstrStatus;
        pBrowser->get_StatusText(&bstrStatus);
  
        // shows using the Win32 function 
        // to free the memory for the string: 
        ::SysFreeString(bstrStatus);
  

• When you implement a function that returns a BSTR, allocate the string but do not free it. The receiving the function releases the memory. For example:

  HRESULT CMyClass::get_StatusText(BSTR* pbstr)
  {
     try
     {
        //m_str is a CString in your class
        *pbstr = m_str.AllocSysString();
     }
     catch (...)
     {
        return E_OUTOFMEMORY;
     }
  
     // The client is now responsible for freeing pbstr.
     return(S_OK);
  }
  

See Also

Strings (ATL/MFC)
CStringT::AllocSysString
SysAllocString
SysFreeString