This documentation is archived and is not being maintained.

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);
    }
    
Show: