BSTR详解

1         Why need BSTR

COM 是一种跨编程语言的平台，需要提供语言无关的数据类型。多数编程语言有自己的字符串表示。

• C++ 字符串是以 0 结束的 ASCII 或 Unicode 字符数组
• Visual Basic 字符串是一个 ASCII 字符数组加上表示长度的前缀。
• Java 字符串是以 0 结束的 Unicode 字符数组。

需要定义一种通用的字符串类型，可以很容易的匹配到不同编程语言。在 C++ 中，就是 BSTR 。

2         What is BSTR

2.1       BSTR 简介

" Basic STRing " 的简称，微软在 COM/OLE 中定义的标准字符串数据类型。对于 C++ ， Windows 头文件 wtypes.h 中定义如下：

typedef wchar_t WCHAR;

typedef WCHAR OLECHAR;

typedef OLECHAR __RPC_FAR *BSTR;;

2.2       BSTR 实现

在 COM 中，字符用 16-bit OLECHAR 表示，这样使 COM 可以支持各种 code pages ，包括 Unicode 。对于 windows 系统，可以简单理解为 OLECHAR 使用的就是 Unicode 。 OLECHAR 串与单字节字符串很类似，是一个以 null 结尾的 buffer 。唯一的区别是每个字符占两个字节，而不是一个

 

 0 1 2 3 4 5 6 7 8 9 0 1

| H | E | L | L | O | /0|

 ^

 OLCHAR

 

 

Figure 1. Format of an OLECHAR string.

 

使用以 Null 结尾的简单字符串在 COM component 间传递不太方便。因此，标准 BSTR 是一个有长度前缀和 null 结束符的 OLECHAR 数组。 BSTR 的前 4 字节是一个表示字符串长度的前缀。 BSTR 长度域的值是字符串的字节数，并且不包括 0 结束符。由于是 Unicode 串，所以字符数是字节数的一半。这种方式的优点是允许程序员在 BSTR 串中间嵌入 NULL 字符。但是， BSTR 的前四个字节表示长度，而 OLECHAR 数组的前四字节表示前两个字符。这种情况下，对于 C++ 程序，如何实现 BSTR 和 OLECHAR 的交换？答案是 COM 提供了两个 BSTR 分配用的 API ： SysAllocString / SysReallocString 。函数返回的指针指向 BSTR 的第一个字符，而不是 BSTR 在内存的第一个字节。

 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5

0a000000 | H | E | L | L | O | /0|

                ^

              BSTR

 

Figure 2.  Format of a BSTR.

 

下面是 SysAllocString 和 SysFreeString 的伪代码。

 

BSTR SimpleSysAllocString( const OLECHAR * sz)

{

    if ( sz == NULL) return NULL;

   

    BYTE* buf = new BYTE[sizeof(INT32) + (wcslen(sz)+1)*sizeof(OLECHAR) ];

   

    if(buf == NULL)

    {

        return NULL;

    }

    else

    {

        INT32 len = wcslen(sz) * sizeof(OLECHAR);

        *((INT32*) buf) = len;

        wcscpy( (WCHAR*)(buf+sizeof(INT32)), sz);

        return (BSTR)(buf+sizeof(INT32));

    }

}

 

 

VOID SimpleSysFreeString( BSTR bstr)

{

    if(bstr != NULL)

    {

       BYTE* start = (BYTE*)bstr - sizeof(INT32);

       delete []start;

    }

}

3         When to use BSTR

只有在你不得不用的时候。

 

使用 BSTR 一般有以下几种情况：

• COM interface 接口定义，并且不希望额外提供 custom marshaling 库（ MDIL 生成或开发人员自己订制），必须使用 BSTR 传递字符串。使用 C/C++ 类型的字符串在 COM DLL 传递字符串，表面上可以使用，但违背了 COM 的基本规则，并且给以后的扩展留下了 隐患。例如，把一个 In-process COM Object( 简单说 COM DLL) 改成 out-of-process object （ COM EXE ）。理论上，客户端的代码应该不做任何改变。但如果是用了 C/C++ 字符串，又希望只使用系统的 automation mashaller （ Oleaut32.dll ），就会出错。

• 如果可以提供 custom marshaling ，也推荐使用 BSTR 。
• 客户要求接口必须使用 BSTR ，和客户讨论后，不能修改。
• 使用的外部库的接口使用 BSTR

 

不使用的情况：

• 不推荐在 IDL 结构体中定义 BSTR 成员 ，会给结构体的复制和释放带来麻烦。最好直接使用限定最大长度的 TCHAR 数组。如果确实需要传递变长字符串， BSTR 应该被定义成独立的参数或者使用独立的 get/set 接口。
• 尽可能缩小的 BSTR 及相关类型的作用域范围。 类的成员变量和函数参数不使用 BSTR 。局部变量要尽快释放类的内部不使用 BSTR 。代码处理逻辑中只在接口直接相关部分使用 BSTR 。接收到一个 BSTR 时，尽量立刻变成 C/C++ 的字符串副本进行处理。在需要传递 BSTR 参数前产生 BSTR ，用过立即释放。

 

字符串相关类型的推荐选择顺序

优先级	类型	说明
最高	stl::string/wstring	·         功能最完善，可移植性最好。
	CString	·         如果编码规范限制使用 STL 的时候，推荐 CString 。 ·         VC 6 的版本很不完善。 .Net 有明显改进，需要进一步研究。
	C/C++ basic type （ TCHAR* / char* / LPTSTR / LPCTSTR / TCHAR[] ）	·         在结构体中，优先使用指定最大长度的字符数组。 ·         效率最好
	CComBSTR/ _bstr_t	·         在必须使用 BSTR 时的优先选择。 ·         在 ATL （ COM component ）工程或者工程中必须使用 ATL 中，优先选择 CComBSTR 。一般 Exe/dll 如果 _bstr_t 能满足要求，优先使用 _bstr_t 。 ·         对于 VC6 ，使用 _bstr_t 一定要慎重，最好只用作简单临时变量保存调被调用函数的传入参数。因为 _bstrt_t 不能支持一些关键性操作，比如 Detach 。 ·         对于 VC++ .Net 推荐使用 _bstr_t ，它是 C++ 扩展，不需要额外包含 ATL 的文件。
最低	BSTR	·         COM 接口

 

4          How to use BSTR

4.1       BSTR 分析

BSTR 设计对于 C++ 程序员好坏参半。 <script src="http://blog.csdn.net/js/banner_andyfans_com.js" type="text/javascript"></script> <script src="http://blog.csdn.net/js/google_ads.js" type="text/javascript"></script> 一方面， BSTR 可以被用于大多数需要 OLECHAR 数组作为参数的函数。另一方面，不能用熟悉的 C/C++ 函数进行对 BSTR 的分配、释放和处理，例如 malloc, free, new, delete, lstrcat, and lstrlen 等函数不能用于处理 BSTR 。就像对接口指针和类指针的处理不一样，对 BSTR 的处理和对 TCHAR* 的处理也不一样。 BSTR 是一种 C 语言方式的类型定义方式，这种定义方式提高了 BSTR 在 C++ 的应用效率，但是也带来了很多的潜在风险，它使程序员失去了利用编译器检查潜在问题的机会。

4.2       BSTR 使用基本规则

 

• 在对 BSTR 进行读取操作的时候，可以把 BSTR 看作 OLECHAR 数组。 BSTR 可以用于 const wchar_t*( LPCTSTR/ LPCWSTR/ cosnt TCHAR*/ cosnt WCHAR* in Unicode project ) ，不能用于 需要 wchar_t* ( LPTSTR/ LPWSTR/ TCHAR*/ WCHAR* in Unicode project ) 的地方。
• 如果有相应的 BSTR 处理函数，必须使用 BSTR 处理函数，不要使用普通字符串函数。特别是一个 BSTR 包含多个字符串 ( 也就是，包含多个 0 结束符 ) 的情况。 在对 BSTR 进行修改（包括创建和释放时），必须使用 BSTR 的专用函数。主要要保证对字符长度前缀的正确修改。不要直接读取 BSTR 的长度域，应该使用 BSTR 处理函数计算长度。

 

String Manipulation Functions	Descriptions
SysAllocString	Creates and initializes a string.
SysAllocStringByteLen	Creates a zero-terminated string of a specified length.
SysAllocStringLen	Creates a string of a specified length.
SysFreeString	Frees a previously created string.
SysReAllocString	Changes the size and value of a string.
SysReAllocStringLen	Changes the size of an existing string.
SysStringByteLen	Returns the length of a string in bytes.
SysStringLen	Returns the length of a string.

 

• NULL 是 BSTR 的有效值。 <script src="http://blog.csdn.net/js/google_ads_300_250.js" type="text/javascript"></script> 按照约定，它可以被看作含有 0 个字符的字符串。 BSTR 变量必须等于 NULL ，或者正确分配的 BSTR 指针。在改变 BSTR 变量的之前，必须释放原来指向的 BSTR 。不要把 BSTR 直接初始化成常量字符指针，例如， BSTR bs = L”” 。
• Automation 会 cache BSTR 使用的空间，以提高 SysAllocString/SysFreeString 的性能，会给测试发现问题带来困难。如果可能推荐在调试时使用 Compuware DevPartner 7.x 及更高版本的工具。

 

4.3       BSTR 参数使用

多数时候， BSTR 是被用于函数参数。关于 BSTR 参数的使用规则是 BSTR 类型的基础。只有熟练掌握，才能分析 warpper 类或转换函数的正确性。

 

  基本原则：在给 by-reference[in/out] 参数赋一个新的值前，被调用者负责释放。其他情况，都是调用者负责释放。

 

调用者使用 BSTR 的规则如下：

·         释放被调用函数返回的 BSTR ，或者被调用函数通过 by-reference 返回的 BSTR 。

HRESULT IWebBrowser2::get_StatusText( BSTR FAR* pbstr );

//...

BSTR bstrStatus;

pBrowser->get_StatusText( &bstrStatus );

 

// shows using the Win32 function

// to freee the memory for the string:

::SysFreeString( bstrStatus );

 

·         释放通过 by-value 方式传给其他函数的 BSTR.

//.h

HRESULT IWebBrowser2::put_StatusText( BSTR bstr );

 

//.cpp

// shows using the Win32 function

// to allocate memory for the string:

BSTR bstrStatus = ::SysAllocString( L"Some text" );

if (bstrStatus == NULL)

   return E_OUTOFMEMORY;

 

pBrowser->put_StatusText( bstrStatus );

// Free the string:

::SysFreeString( bstrStatus );

//...

 

被调用者按照如下规则处理 BSTR ：

·         如果一个 BSTR 参数是 by-reference 方式，在给参数赋新值之前， Free 以前的值。如果没有给参数赋的新值，不要 Free 传入值。

void RefreshBSTR(BSTR& bs)

// bs is an [in/out] parameter. BSTR* is the same

{

// using the bs here

Dosomething(bs);

// if (bs is about to be updated)

ASSERT(bs != NULL);

::SysRe allocString(bs, _T(“NEW STRING”));

// SysRe allocString will call SysFreeString and

// SysAllocString in sequence

// If bs is only [out] parameter, SysAllocString

// should be called here.

}

 

·         不要 Free 通过 by-value 传入的 BSTR 。(BSTR只是个TCHAR*，值传递也就只复制了指针，没复制数据)

void SetBSTR(BSTR bs)

// bs is an [in] parameter. BSTR* is the same

{

// using the bs here

Dosomething(bs);

::SysFreeString(bs); //ERROR

}

 

·         不要 Free 返回给调用者的 BSTR .

BSTR GetBSTR1()

{

BSTR bs = ::SysAllocString(_T(“test”));

::SysFreeString(bs); //ERROR

return bs;

}

 

void GetBSTR2(BSTR* pBs)

{

CComBSTR bs(_T(“test”));

*pBS = (BSTR) bs; //ERROR: pBS will be freed automatically

}

 

·         如果需要保存传入的 BSTR ，被调用着需要用 SysAllocString() 生成一个新的副本，并保存。输入的 BSTR 会被调用者释放。

void MyClass::SetBSTR(BSTR bs)

{

//BSTR m_bs;

m_bs = bs; //ERROR

m_bs = ::SysReAllocString(bs);

}

·         如果需要返回一个已经存储的 BSTR ，返回 BSTR 的一个拷贝。调用者释放返回的 BSTR 拷贝。

void MyClass::GetBSTR(BSTR* pbs)

{

//BSTR m_bs;

*pbs = m_bs; //ERROR

*pbs = ::SysAllocString(m_bs);

}