COM 是一种跨编程语言的平台,需要提供语言无关的数据类型。多数编程语言有自己的字符串表示。
- C++ 字符串是以 0 结束的 ASCII 或 Unicode 字符数组
- Visual Basic 字符串是一个 ASCII 字符数组加上表示长度的前缀。
- Java 字符串是以 0 结束的 Unicode 字符数组。
需要定义一种通用的字符串类型,可以很容易的匹配到不同编程语言。在 C++ 中,就是 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
下面是 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;
}
}
只有在你不得不用的时候。
使用 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.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);
}