What is BSTR? How it differs from an array of unicode wchar_t?

WCHAR

unicode wchar_t is 16 bit char variable in COM/OLE, is also known as wide character. Wide character array/string can give Multilanguage language support.

 typedef CHAR char;

 typedef WCHAR short;

 typedef STRING CHAR*;

 typedef WSTRING WCHAR*;

BSTR

BSTR is a kind of array of wide chars. The difference is BSTR holds the length of the string in the header and the content follows the header. The first 16bit/2 byte holds the length of the string and rest of the bytes contains the wide chars. All the out-of-process COM/DCOM uses this BSTR because when the string has to be transported through RPC the length indicates how many bytes should follow after header of BSTR.

BSTR memory layout
Header 16 bit(length)	Body (Length * sizeof(wchar_t)

Allocate BSTR

BSTR can be allocated using SysAllocString() API using header file oleauto.h. It takes an WIDE string or unicode string and returns the BSTR buffer. A failure case is handled by returning NULL to the caller.

 BSTR SysAllocString(

   const OLECHAR *psz

 );

Free BSTR

BSTR allocated using SysAllocString() API should be deallocated using SysFreeString(). All the BSTR APIs are part of oleauto.h header file.

 void SysFreeString(

   BSTR bstrString

 );

Note: Programmer should not use malloc or free calls for BTRs allocation and deallocation process.

Allocate & free BSTR example

Here is an example use of BSTR with webbrowser navigate method. We are allocation the URL BSTR string from an UNICODE string and using in IWebBrowser.Navigate(URL) call. Once the call is made we are deallocating it.

  DISPID named;

   VARIANT *args;

   args = new VARIANT[1];

   named = DISPID_PROPERTYPUT;

   VariantInit(&args[0]);

   args[0].bstrVal = SysAllocString(L"http://www.google.com/");

   dp.rgvarg = args;

   dp.cArgs = 1;

   dp.rgdispidNamedArgs = NULL;

   dp.cNamedArgs = 0;

   /* IWebBrowser.Navigate(URL) using Invoke */

   pBrowser->Invoke(IeMethodNavigate,

                    IID_NULL,

                    LOCALE_SYSTEM_DEFAULT,

                    DISPATCH_METHOD,

                    &dp,NULL,NULL,&nErr);

   ..

   SysFreeString(args[0].bstrVal);

Function returning BSTR example

In the above case we are having an example of call by value. The caller is allocating the string and passing to an external method. Now another case is possible where the interface method is allocating the string and that is returned to the caller. This is known as call by reference and returned by reference. The caller is providing the reference BSTR address to the method and the method is allocating it and returning the same. In this case the parameter is known as [out,retval] parameter in DCOM terminology. The caller is responsible for the deallocation of this BSTR buffer. A memory leak might happen if the caller misses to call the SysFreeString.

 /* Allocation of BSTR in external DCOM */

 HRESULT CExternalInterface::get_SearchUrl(BSTR* pbstr)

 {

   HRESULT hr;

   if(!pbstr)

   {

     return E_INVALIDARG;

   }

   /* The client is now responsible for freeing pbstr. */

   *pbstr = SysAllocString(L"http://www.google.com/");

   if (*pbstr)

   {

     return(S_OK);

   }

   else

   {

     return E_OUTOFMEMORY;

   } 

 }

 /* DCOM client */

 void GetSearchUrl()

 {

   BSTR bstrUrl;

   if ( pExternalInterface->get_SearchUrl(&bstrUrl) == S_OK)

   {

     .....

     .....

     /* Use bstrUrl then free it */

     SysFreeString(bstrUrl);

    }

 }

About our authors: Team EQA

You have viewed 1 page out of 67. Your COM/DCOM learning is 0.00% complete. Login to check your learning progress.

‹ # ›