SAFEARRAY

我们将使用SAFEARRAY来通过COM传送串行化的对象。这部分将介绍如何建立和使用SAFEARRAY类型。

　　SAFEARRAY是数据结构的一种。这种结构也没有什么特别的，你只需要正确地设置它，当然你要知道其中一些颇为复杂的规定。为了确保SAFEARRAY被正确地使用，它有一系列用作管理的API函数。这些API的函数负责创建、调整大小和删除SAFEARRAY。不幸的是，有关这些API函数的文档是相当少的。

　　对于SAFEARRAY的内部结构我们并不关心，但了解一下是值得的。以下就是SAFEARRAY的Win32定义：

　　typedef struct tagSAFEARRAY

　　　{

　　　　unsigned short cDims;

　　　　unsigned short fFeatures;

　　　　unsigned long cbElements;

　　　　unsigned long cLocks;

　　　　void * pvData;

　　　　SAFEARRAYBOUND rgsabound[ 1 ];

　　　} SAFEARRAY;

　　这个结构的成员（cDims，cLocks等）是通过API函数来设置和管理的。真正的数据存放在pvData成员中，而SAFEARRAYBOUND结构定义该数组结构的细节。以下就是该结构成员的简要描述：


成员 描述 
cDims 数组的维数 
fFeatures 用来描述数组如何分配和如何被释放的标志 
cbElements 数组元素的大小 
cLocks 一个计数器，用来跟踪该数组被锁定的次数 
pvData  指向数据缓冲的指针 
rgsabound 描述数组每维的数组结构，该数组的大小是可变的 

　　rgsabound是一个有趣的成员，它的结构不太直观。它是数据范围的数组。该数组的大小依safe array维数的不同而有所区别。rgsabound成员是一个SAFEARRAYBOUND结构的数组--每个元素代表SAFEARRAY的一个维。

　　typedef struct tagSAFEARRAYBOUND

　　　{

　　　　unsigned long cElements;

　　　　unsigned long lLbound;

　　　} SAFEARRAYBOUND;

　　维数被定义在cDims成员中。例如，一个'C'类数组的维数可以是[3][4][5]-一个三维的数组。如果我们使用一个SAFEARRAY来表示这个结构，我们定义一个有三个元素的rgsabound数组--一个代表一维。

　　cDims = 3;


　　　 ...


　　SAFEARRAYBOUND rgsabound[ 3 ];

　　rgsabound[0]元素定义第一维。在这个例子中ILBOUND元素为0，是数组的下界。cElements成员的值等于三。数组的第二维（[4]）可以被rgsabound结构的第二个元素定义。下界也可以是0，元素的个数是4，第三维也是这样。要注意，由于这是一个"C"数组，因此由0开始，对于其它语言，例如Visual Basic，或者使用一个不同的开始。该数组的详细情况如下所示：


元素 cElements ILbound 
rgsabound[0]  3  0 
rgsabound[1] 4  0 
rgsabound[2] 5 0 


　　关于SAFEARRAYBOUND结构其实还有很多没说的。我们将要使用的SAFEARRAY只是一个简单的单维字节数组。我们通过API函数创建数组的时候，SAFEARRAYBOUND将会被自动设置。只有在你需要使用复杂的多维数组的时候，你才需要操作这个结构。

　　还有一个名字为cLocks的成员变量。很明显，它与时间没有任何的关系--它是一个锁的计数器。该参数是用来控制访问数组数据的。在你访问它之前，你必须锁定数据。通过跟踪该计数器，系统可以在不需要该数组时安全地删除它。

创建SAFEARRAY

　　创建一个单维SAFEARRAY的简单方法是通过使用SafeArrayCreateVector API函数。该函数可分配一个特定大小的连续内存块。

　　SAFEARRAY *psa;

　　file:// create a safe array to store the stream data

　　file:// llen is the number of bytes in the array.


　　psa = SafeArrayCreateVector( VT_UI1, 0, llen );

　　SafeArrayCreateVector API创建一个SAFEARRAY，并且返回一个指向它的指针。首个参数用来定义数组的类型--它可以是任何有效的变量数据类型。为了传送一个串行化的对象，我们将使用最基本的类型--一个非负的字节数组。VT--UI1代表非负整形的变量类型，1个字节。

　　常数'0'定义数组的下界；在C++中，通常为0。最后的参数llen定义数组元素的个数。在我们的例子中，这与我们将要传送对象的字节数是一样的。我们还没有提数组大小（llen）是怎样来的，这将在我们重新考查串行化时提及。

　　在你访问SAFEARRAY数据之前，你必须调用SafeArrayAccessData。该函数锁定数据并且返回一个指针。在这里，锁定数组意味着增加该数组的内部计数器（cLocks）。

　　file:// define a pointer to a byte array

　　unsigned char *pData = NULL;

　　SafeArrayAccessData( psa, (void**)&pData );

　　　... use the safe array

　　SafeArrayUnaccessData(psa);

　　相应用来释放数据的函数是SafeArrayUnaccessData()，该功能释放该参数的计数。





类型 名字  描述 
byte VT_UI1 非负字节 
short VT_I2 有符号16位短整型 
long VT_I4 有符号32位长整型 
float VT_R4 一个IEEE 4字节实型数字 
double VT_R8 一个IEEE 8字节实型数字 
VARIANT_BOOL VT_BOOL 16位布尔 0=false, 0xFFFF=true 
SCODE  VT_ERROR 16位错误码 
CY  VT_CY  16位货币结构 
DATE VT_DATE  使用双精度数字表示的日期 
BSTR  VT_BSTR  visual basic风格的字符结构 
DECIMAL VT_DECIMAL 一个十进制的结构 
IUnknown VT_UNKNOWN  一个COM接口的指针 
IDispatch VT_DISPATCH COM Dispatch接口的指针 
SAFEARRAY * VT_ARRAY 一个用作传送数组数据的特别结构 
VARIANT * VT_VARIANT 一个VARIANT结构的指针 
void  * 普通的指针 
 VT_BYREF 任何类型（除指针外）的指针 

 

SAFEARRAY的主要目的是用于automation中的数组型参数的传递。因为在网络环境中，数组是不能直接传递的，而必须将其包装成SafeArray。实质上SafeArray就是将通常的数组增加一个描述符，说明其维数、长度、边界、元素类型等信息。SafeArray也并不单独使用，而是将其再包装到VARIANT类型的变量中，然后才作为参数传送出去。在VARIANT的vt成员的值如果包含VT_ARRAY|...,那么它所封装的就是一个SafeArray，它的parray成员即是指向SafeArray的指针。 SafeArray中元素的类型可以是VARIANT能封装的任何类型，包括VARIANT类型本身。

使用SafeArray的具体步骤：

2方法一

包装一个SafeArray

(1). 定义变量，如：

VARIANT varChunk;

SAFEARRAY *psa;

SAFEARRAYBOUND rgsabound[1];

(2). 创建SafeArray描述符：

uIsRead=f.Read(bVal,ChunkSize);//read array from a file.

if(uIsRead==0)break;

rgsabound[0].cElements =uIsRead;

rgsabound[0].lLbound = 0;

psa = SafeArrayCreate(VT_UI1,1,rgsabound);

(3). 放置数据元素到SafeArray：

for(long index=0;index<uIsRead;index++)

{

if(FAILED(SafeArrayPutElement(psa,&index,&bVal)))

::MessageBox(NULL,"出毛病了。","提示",MB_OK | MB_ICONWARNING);

}

一个一个地放，挺麻烦的。

(4). 封装到VARIANT内：

varChunk.vt = VT_ARRAY|VT_UI1;

varChunk.parray = psa;

这样就可以将varChunk作为参数传送出去了。

读取SafeArray中的数据的步骤：

(1). 用SafeArrayGetElement一个一个地读

BYTE buf[lIsRead];

for(long index=0;index<lIsRead;index++)

{

::SafeArrayGetElement(varChunk.parray,&index,buf+index);

}

就读到缓冲区buf里了。

3方法二

用SafeArrayAccessData直接读写SafeArray缓冲区：

(1). 读缓冲区：

BYTE *buf;

SafeArrayAccessData(varChunk.parray, (void **)&buf);

f.Write(buf,lIsRead);

SafeArrayUnaccessData(varChunk.parray);

(2). 写缓冲区：

BYTE *buf;

::SafeArrayAccessData(psa, (void **)&buf);

for(long index=0;index<uIsRead;index++)

{

buf=bVal;

}

::SafeArrayUnaccessData(psa);

varChunk.vt = VT_ARRAY|VT_UI1;

varChunk.parray = psa;

这种方法读写SafeArray都可以，它直接操纵SafeArray的数据缓冲区，比用SafeArrayGetElement和 SafeArrayPutElement速度快。特别适合于读取数据。但用完之后不要忘了调用::SafeArrayUnaccessData (psa)，否则会出错的。

如果SafeArray中存的是BSTR的二维数组,则代码如下：

if(varChunk.vt = VT_ARRAY | VT_BSTR)

{

BSTR* buf;

long LBound; // 数组下界

long UBound; // 数组上界

SafeArrayAccessData(varChunk.parray, (void **)&buf);

SafeArrayGetLBound(varChunk.parray, 1, &LBound);

SafeArrayGetUBound(varChunk.parray, 1, &UBound);

for(long i = LBound; i < UBound; i ++)

{

CString str(buf);

MessageBox(str);

}

SafeArrayUnaccessData(varChunk.parray);

}