關於SafeArray的使用說明(轉)

  猛料資料，首先介紹SafeArray使用，在介紹SafeArray中的結構。看完該節文章，SafeArray的陌生感一掃而去。

    SafeArray 在ADO編程中常常使用。它的主要目的是用於automation中的數組型參數的傳遞。由於在網絡環境中，數組是不能直接傳遞的，而必須將其包裝成 SafeArray。實質上SafeArray就是將一般的數組增長一個描述符，說明其維數、長度、邊界、元素類型等信息。SafeArray也並不單獨使用，而是將其再包裝到VARIANT類型的變量中，而後才做爲參數傳送出去。在VARIANT的vt成員的值若是包含VT_ARRAY|...,那麼它所封裝的就是一個SafeArray，它的parray成員便是指向SafeArray的指針。SafeArray中元素的類型能夠是VARIANT能封裝的任何類型，包括VARIANT類型自己。 

使用SafeArray的具體步驟：

方法一：

 包裝一個SafeArray：

(1)定義變量，如：

   VARIANT varChunk;

   SAFEARRAY *psa;

   SAFEARRAYBOUND rgsabound[1];

(2) 建立SafeArray描述符：

 //read array from a file.

 uIsRead=f.Read(bVal,ChunkSize);

 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[index])))

    ::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裏了。

方法二：

 使用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[index]=bVal[index]; 

 }

 ::SafeArrayUnaccessData(psa);

 varChunk.vt = VT_ARRAY|VT_UI1;

 varChunk.parray = psa;

   

    這種方法讀寫SafeArray均可以，它直接操縱SafeArray的數據緩衝區，比用SafeArrayGetElement和 SafeArrayPutElement速度快。特別適合於讀取數據。但用完以後不要忘了調用::SafeArrayUnaccessData (psa)，不然會出錯的。

如下就是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;

　　//  create a safe array to store the stream data

　　//  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）。

　　//  define a pointer to a byte array

　　unsigned char *pData = NULL;

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

　　　... use the safe array

　　SafeArrayUnaccessData(psa);

　　相應用來釋放數據的函數是SafeArrayUnaccessData()，該功能釋放該參數的計數。