Rules for Freeing BSTRs in OLE Automation

 Last reviewed: May 17, 1995
Article ID: Q108934
The information in this article applies to:
  • Microsoft OLE Libraries for Windows and Win32s, version 2.01
  • Microsoft OLE Libraries, included with: 

        - Microsoft Windows NT, versions 3.5 and 3.51
    - Microsoft Windows 95

SUMMARY

The callee frees a BSTR passed in as a by-reference parameter before assigning the parameter a new value. In all other cases, the caller frees the BSTR.

MORE INFORMATION

OLE Automation defines the BSTR data type to handle strings that are allocated by one component and freed by another. The rule for freeing a BSTR is as follows:

The callee frees a BSTR passed in as a by-reference parameter before assigning the parameter a new value. In all other cases, the caller frees the BSTR.

In other words, the caller handles BSTRs as follows:

  1. Free BSTR returned by called function or returned through a by- reference parameter of called function.

  2. Free BSTR passed as a by-value parameter to a function.

The callee handles BSTRs as follows:

  1. Free BSTR passed in as a by-reference parameter before assigning a new value to the parameter. Do not free if a new value is not assigned to the by-reference parameter.

  2. Do not free BSTR passed in as a by-value parameter.

  3. Do not free BSTR that has been returned to caller.

  4. If a BSTR passed in by the caller is to be stored by the callee, store a copy using SysAllocString(). The caller will release the BSTR that it passed in.

  5. If a stored BSTR is to be returned, return a copy of the BSTR. The caller will release the BSTR that is returned.

Additional reference words: 2.01 3.50 4.00
KBCategory: kbole kbprg
KBSubcategory: LeTwoAto

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: May 17, 1995
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.