COleSafeArray 類別

類別，用來處理任意類型和維度的陣列。

語法

class COleSafeArray : public tagVARIANT

成員

公用建構函式

名稱	描述
COle保管庫Array：：COle保管庫Array	建構 COleSafeArray 物件。

公用方法

名稱	描述
COle保管庫Array：：AccessData	擷取陣列資料的指標。
COle保管庫Array：：AllocData	配置陣列的記憶體。
COle保管庫Array：：AllocDescriptor	配置安全陣列描述元的記憶體。
COle保管庫Array：：Attach	將現有 VARIANT 陣列的控制提供給 COleSafeArray 物件。
COle保管庫Array：：Clear	釋放基礎 VARIANT 中的所有資料。
COle保管庫Array：：Copy	建立現有陣列的複本。
COle保管庫Array：：Create	建立安全陣列。
COle保管庫Array：：CreateOneDim	建立一維 COleSafeArray 物件。
COle保管庫Array：:D estroy	終結現有的陣列。
COle保管庫Array：:D estroyData	終結安全陣列中的資料。
COle保管庫Array：:D estroyDescriptor	終結安全陣列的描述項。
COle保管庫Array：:D etach	將 VARIANT 陣列與 COleSafeArray 物件中斷連結（因此不會釋放資料）。
COle保管庫Array：：GetByteArray	將安全陣列 的內容複寫到 CByteArray 。
COle保管庫Array：：GetDim	傳回陣列中的維度數目。
COle保管庫Array：：GetElement	擷取安全陣列的單一元素。
COle保管庫Array：：GetElemSize	傳回安全陣列中一個專案的大小，以位元組為單位。
COle保管庫Array：：GetLBound	傳回安全陣列之任何維度的下限。
COle保管庫Array：：GetOneDimSize	傳回一維 COleSafeArray 物件中的專案數目。
COle保管庫Array：：GetUBound	傳回安全陣列之任何維度的上限。
COle保管庫Array：：Lock	遞增陣列的鎖定計數，並將指標放在陣列描述元中的陣列資料。
COle保管庫Array：:P trOfIndex	傳回索引項目目的指標。
COle保管庫Array：:P utElement	將單一項目指派到陣列。
COle保管庫Array：：Redim	變更安全陣列的最小有效（最右邊）界限。
COle保管庫Array：：ResizeOneDim	變更一維 COleSafeArray 物件中的專案數目。
COle保管庫Array：：UnaccessData	遞減陣列的鎖定計數，並使 所擷取的 AccessData 指標失效。
COle保管庫Array：：Unlock	遞減陣列的鎖定計數，以便釋放或調整大小。

公用運算子

名稱	描述
COle保管庫Array：：operator LPCVARIANT	存取 物件的基礎 VARIANT 結構 COleSafeArray 。
COle保管庫Array：：operator LPVARIANT	存取 物件的基礎 VARIANT 結構 COleSafeArray 。
COle保管庫Array：：operator =	將值複製到 COleSafeArray 物件 （ SAFEARRAY 、、 VARIANTCOleVariant 或 COleSafeArray 陣列）。
COle保管庫Array：：operator ==	比較兩個變體陣列 （ SAFEARRAY 、 VARIANT 、 COleVariant 或 COleSafeArray 陣列）。
COleSafeArray::operator <<	將 物件的內容 COleSafeArray 輸出至傾印內容。

備註

COleSafeArray 衍生自 OLE VARIANT 結構。 OLE SAFEARRAY 成員函式可透過 COleSafeArray 取得，以及專為位元組一維陣列設計的一組成員函式。

繼承階層架構

tagVARIANT

COleSafeArray

需求

標頭： afxdisp.h

COle保管庫Array：：AccessData

擷取陣列資料的指標。

void AccessData(void** ppvData);

參數

ppvData
陣列資料的指標。

備註

發生錯誤時，函式會 擲回 CMemoryException 或 COleException 。

範例

void CMainFrame::Sort(VARIANT* vArray)
{
   COleSafeArray sa;
   BSTR* pbstr;
   TCHAR buf[1024];
   LONG cElements, lLBound, lUBound;

   //needed for OLE2T macro below, include afxpriv.h
   USES_CONVERSION;

   // Type check VARIANT parameter. It should contain a BSTR array
   // passed by reference. The array must be passed by reference it is
   // an in-out-parameter.
   if (V_VT(vArray) != (VT_ARRAY | VT_BSTR))
   {
      AfxThrowOleDispatchException(1001,
         _T("Type Mismatch in Parameter. Pass a string array by reference"));
   }

   // clears data in sa and copies the variant data into sa
   sa.Attach(*vArray);

   // Check that array is 1 dimensional
   if (sa.GetDim() != 1)
   {
      AfxThrowOleDispatchException(1002,
         _T("Type Mismatch in Parameter. Pass a one-dimensional array"));
   }

   try
   {
      // Get array bounds.
      sa.GetLBound(1, &lLBound);
      sa.GetUBound(1, &lUBound);

      // Get a pointer to the elements of the array
      // and increments the lock count on the array
      sa.AccessData((LPVOID*)& pbstr);

      //get no. of elements in array
      cElements = lUBound - lLBound + 1;
      for (int i = 0; i < cElements; i++)
      {
         //output the elements of the array
         _stprintf_s(buf, 1024, _T("[%s]\n"), OLE2T(pbstr[i]));
         OutputDebugString(buf);
      }

      //decrement lock count
      sa.UnaccessData();
   }
   catch (COleException* pEx)
   {
      AfxThrowOleDispatchException(1003,
         _T("Unexpected Failure in FastSort method"));
      pEx->Delete();
   }
}

COle保管庫Array：：AllocData

配置安全陣列的記憶體。

void AllocData();

備註

發生錯誤時，函式會 擲回 CMemoryException 或 COleException 。

COle保管庫Array：：AllocDescriptor

配置安全陣列描述元的記憶體。

void AllocDescriptor(DWORD dwDims);

參數

dwDims
安全陣列中的維度數目。

備註

發生錯誤時，函式會 擲回 CMemoryException 或 COleException 。

COle保管庫Array：：Attach

將現有 VARIANT 陣列 COleSafeArray 中的資料控制權提供給 物件。

void Attach(VARIANT& varSrc);

參數

varSrc
VARIANT 物件。 varSrc 參數必須具有 VARTYPE VT_ARRAY 。

備註

來源 VARIANT 的類型會設定為 VT_EMPTY。 如果有任何，此函式會清除目前的陣列資料。

範例

請參閱 COle保管庫Array：：AccessData 的 範例。

COle保管庫Array：：Clear

清除安全陣列。

void Clear();

備註

函式會將 物件的 設定 VARTYPE 為 VT_EMPTY，以清除安全陣列。 目前的內容會釋出，而且會釋放陣列。

COle保管庫Array：：COle保管庫Array

建構 COleSafeArray 物件。

COleSafeArray();

COleSafeArray(
    const SAFEARRAY& saSrc,
    VARTYPE vtSrc);

COleSafeArray(
    LPCSAFEARRAY pSrc,
    VARTYPE vtSrc);

COleSafeArray(const COleSafeArray& saSrc);
COleSafeArray(const VARIANT& varSrc);
COleSafeArray(LPCVARIANT pSrc);
COleSafeArray(const COleVariant& varSrc);

參數

saSrc
現有的 COleSafeArray 物件，或 SAFEARRAY 要複製到新的 COleSafeArray 物件中。

vtSrc
新 COleSafeArray 物件的 VARTYPE。

psaSrc
要複製到新 COleSafeArray 物件之 的指標 SAFEARRAY 。

varSrc
要複製到新 COleSafeArray 物件的現有 VARIANT 或 COleVariant 物件。

pSrc
要複製到新 COleSafeArray 物件之物件的指標 VARIANT 。

備註

所有這些建構函式都會建立新的 COleSafeArray 物件。 如果沒有參數，則會建立空 COleSafeArray 的物件（VT_EMPTY）。 COleSafeArray如果 從另一個已知 VARTYPE 的陣列複製 ， COleSafeArrayCOleVariantVARIANT 則會保留來源陣列的 VARTYPE，而且不需要指定。 COleSafeArray如果 從另一個陣列複製 ，且其 VARTYPE 未知 （ SAFEARRAY ），則必須在 vtSrc 參數中指定 VARTYPE。

發生錯誤時，函式會 擲回 CMemoryException 或 COleException 。

COle保管庫Array：：Copy

建立現有安全陣列的複本。

void Copy(LPSAFEARRAY* ppsa);

參數

ppsa
要在其中傳回新陣列描述元的位置指標。

備註

發生錯誤時，函式會 擲回 CMemoryException 或 COleException 。

COle保管庫Array：：Create

配置和初始化陣列的資料。

void Create(
    VARTYPE vtSrc,
    DWORD dwDims,
    DWORD* rgElements);

void Create(
    VARTYPE vtSrc,
    DWORD dwDims,
    SAFEARRAYBOUND* rgsabounds);

參數

vtSrc
陣列的基底類型（也就是陣列中每個專案的 VARTYPE）。 VARTYPE 僅限於變體類型的子集。 無法設定VT_ARRAY或VT_BYREF旗標。 VT_EMPTY和VT_Null不是陣列的有效基底類型。 所有其他類型都是合法的。

dwDims
陣列中的維度數目。 使用 Redim 建立 陣列之後，即可變更此專案。

rgElements
陣列中每個維度元素數目的指標。

rgsabounds
要為數組配置的界限向量指標（每個維度各一個）。

備註

如有必要，此函式會清除目前的陣列資料。 發生錯誤時，函式會 擲回 CMemoryException 。

範例

COleSafeArray saMatrix;
DWORD numElements[] = { 10, 5 };

// creates a 2 dimensional safearray of type VT_I2 
// with size 10x5 elements, with all indices starting at 0(default)
saMatrix.Create(VT_I2, 2, numElements);

ASSERT(saMatrix.GetDim() == 2);

COleSafeArray saVector;
SAFEARRAYBOUND rgsabounds[] = { {5, 2} };

// creates a 1 dimensional safearray of type VT_I1 
// with size 5 elements, with the index starting at 2
saVector.Create(VT_I1, 1, rgsabounds);

ASSERT(saVector.GetDim() == 1);

COle保管庫Array：：CreateOneDim

建立新的一維 COleSafeArray 物件。

void CreateOneDim(
    VARTYPE vtSrc,
    DWORD dwElements,
    const void* pvSrcData = NULL,
    long nLBound = 0);

參數

vtSrc
陣列的基底類型（也就是陣列中每個專案的 VARTYPE）。

dwElements
陣列中的專案數目。 使用 ResizeOneDim 建立 陣列之後，即可變更此專案。

pvSrcData
要複製到陣列的資料指標。

nLBound
陣列的下限。

備註

函式會配置和初始化陣列的資料，如果指標 pvSrcData 不是 Null，則複製指定的資料。

發生錯誤時，函式會 擲回 CMemoryException 。

範例

VARIANT varColInfo[3];

//initialize VARIANTs
for (int i = 0; i < 3; i++)
   VariantInit(&varColInfo[i]);

// Column Name
varColInfo[0].vt = VT_BSTR;
varColInfo[0].bstrVal = ::SysAllocString(L"Name");

// Column Type
varColInfo[1].vt = VT_UI4;
varColInfo[1].lVal = 1;

COleSafeArray sa;
//create a 1 dimensional safearray of VARIANTs
//& initialize it with varColInfo VARIANT array
sa.CreateOneDim(VT_VARIANT, 2, varColInfo);

//check that the dimension is 2
ASSERT(sa.GetOneDimSize() == 2);

//increase safearray size by 1
sa.ResizeOneDim(3);

// populate the last element of the safearray, (Column Size)
varColInfo[2].vt = VT_I4;
varColInfo[2].lVal = 30;
long el = 2;
sa.PutElement(&el, &varColInfo[2]);

COle保管庫Array：:D estroy

終結現有的陣列描述元和陣列中的所有資料。

void Destroy();

備註

如果物件儲存在陣列中，則會釋放每個物件。 發生錯誤時，函式會 擲回 CMemoryException 或 COleException 。

COle保管庫Array：:D estroyData

終結安全陣列中的所有資料。

void DestroyData();

備註

如果物件儲存在陣列中，則會釋放每個物件。 發生錯誤時，函式會 擲回 CMemoryException 或 COleException 。

COle保管庫Array：:D estroyDescriptor

終結安全陣列的描述項。

void DestroyDescriptor();

備註

發生錯誤時，函式會 擲回 CMemoryException 或 COleException 。

COle保管庫Array：:D etach

從 VARIANT 物件中斷連結資料 COleSafeArray 。

VARIANT Detach();

傳回值

物件中 COleSafeArray 的基礎 VARIANT 值。

備註

函式會將 物件的 VARTYPE 設定為 VT_EMPTY，以中斷連結安全陣列中的資料。 呼叫 Windows 函 式 VariantClear 來釋放陣列是呼叫者的責任。

發生錯誤時，函式會 擲回 COleException 。

範例

請參閱 COle保管庫Array：:P utElement 的範例 。

COle保管庫Array：：GetByteArray

將安全陣列 CByteArray 的內容複寫到 。

void GetByteArray(CByteArray& bytes);

參數

bytes
CByteArray 物件的參考 。

COle保管庫Array：：GetDim

傳回 物件中的 COleSafeArray 維度數目。

DWORD GetDim();

傳回值

安全陣列中的維度數目。

範例

COleSafeArray saMatrix;
DWORD numElements[] = { 10, 5 };

// creates a 2 dimensional safearray of type VT_I2 
// with size 10x5 elements, with all indices starting at 0(default)
saMatrix.Create(VT_I2, 2, numElements);

ASSERT(saMatrix.GetDim() == 2);

COleSafeArray saVector;
SAFEARRAYBOUND rgsabounds[] = { {5, 2} };

// creates a 1 dimensional safearray of type VT_I1 
// with size 5 elements, with the index starting at 2
saVector.Create(VT_I1, 1, rgsabounds);

ASSERT(saVector.GetDim() == 1);

COle保管庫Array：：GetElement

擷取安全陣列的單一元素。

void GetElement(
    long* rgIndices,
    void* pvData);

參數

rgIndices
陣列的每個維度索引陣列的指標。

pvData
要放置陣列專案的位置指標。

備註

此函式會自動呼叫視窗函 SafeArrayLock 式，以及 SafeArrayUnlock 擷取專案前後。 如果資料元素是字串、物件或變體，函式會以正確的方式複製專案。 參數 pvData 應該指向足夠大的緩衝區，以包含 元素。

發生錯誤時，函式會 擲回 CMemoryException 或 COleException 。

範例

//sa is of type COleSafeArray with 2 dimensions

//Determine upper bounds for both dimensions
long lNumRows;
long lNumCols;
sa.GetUBound(1, &lNumRows);
sa.GetUBound(2, &lNumCols);

//Display the elements in the SAFEARRAY.
long index[2];
VARIANT val;

//Determine lower bounds for both dimensions
long lowRow, lowCol;
sa.GetLBound(1, &lowRow);
sa.GetLBound(2, &lowCol);

for (long r = lowRow; r <= lNumRows; r++)
{
   for (long c = lowCol; c <= lNumCols; c++)
   {
      index[0] = r;
      index[1] = c;

      //retrieve each element of the safearray
      sa.GetElement(index, &val);

      switch (val.vt)
      {
      case VT_R8:
         TRACE(_T("%1.2f\n"), val.dblVal);
         break;

      case VT_BSTR:
         TRACE(_T("%s\n"), (CString)val.bstrVal);
         break;

         // other cases omitted

      case VT_EMPTY:
         TRACE(_T("<empty>\n"));
         break;
      }
   }
}

COle保管庫Array：：GetElemSize

擷取 物件中 COleSafeArray 專案的大小。

DWORD GetElemSize();

傳回值

安全陣列元素的大小，以位元組為單位。

COle保管庫Array：：GetLBound

傳回物件之任何維度的 COleSafeArray 下限。

void GetLBound(
    DWORD dwDim,
    long* pLBound);

參數

dwDim
要取得下限的陣列維度。

pLBound
要傳回下限的位置指標。

備註

發生錯誤時，函式會 擲回 COleException 。

範例

COleSafeArray saMatrix;
DWORD numElements[] = { 10, 5 };

// creates a 2 dimensional safearray of type VT_I2 
// with size 10x5 elements, with all indices starting at 0(default)
saMatrix.Create(VT_I2, 2, numElements);

long lLBound;

//get lower bound for 1st dimension
saMatrix.GetLBound(1, &lLBound);

ASSERT(lLBound == 0);

//get lower for 2nd dimension
saMatrix.GetLBound(2, &lLBound);

ASSERT(lLBound == 0);

COleSafeArray saVector;
SAFEARRAYBOUND rgsabounds[] = { {5, 1} };

// creates a 1 dimensional safearray of type VT_I1 
// with size 5 elements, with the index starting at 1
saVector.Create(VT_I1, 1, rgsabounds);

//get lower bound for 1st dimension
saVector.GetLBound(1, &lLBound);

ASSERT(lLBound == 1);

COle保管庫Array：：GetOneDimSize

傳回一維 COleSafeArray 物件中的專案數目。

DWORD GetOneDimSize();

傳回值

一維安全陣列中的專案數目。

範例

請參閱 COle保管庫Array：：CreateOneDim 的範例 。

COle保管庫Array：：GetUBound

傳回安全陣列之任何維度的上限。

void GetUBound(
    DWORD dwDim,
    long* pUBound);

參數

dwDim
要取得上限的陣列維度。

pUBound
要傳回上限的位置指標。

備註

發生錯誤時，函式會 擲回 COleException 。

範例

COleSafeArray saMatrix;
DWORD numElements[] = { 10, 5 };

// creates a 2 dimensional safearray of type VT_I2 
// with size 10x5 elements, with all indices starting at 0(default)
saMatrix.Create(VT_I2, 2, numElements);

long lUBound;
ASSERT(saMatrix.GetDim() == 2);

//get upper bound for 1st dimension
saMatrix.GetUBound(1, &lUBound);

ASSERT(lUBound == 9);

//get upper bound for 2nd dimension
saMatrix.GetUBound(2, &lUBound);

ASSERT(lUBound == 4);

COleSafeArray saVector;
SAFEARRAYBOUND rgsabounds[] = { {5, 1} };

// creates a 1 dimensional safearray of type VT_I1 
// with size 5 elements, with the index starting at 1
saVector.Create(VT_I1, 1, rgsabounds);

//get upper bound for 1st dimension
saVector.GetUBound(1, &lUBound);

ASSERT(lUBound == 5);

COle保管庫Array：：Lock

遞增陣列的鎖定計數，並將指標放在陣列描述元中的陣列資料。

void Lock();

備註

發生錯誤時，它會擲回 COleException 。

陣列描述元中的指標有效，直到呼叫為止 Unlock 。 對 Lock 的呼叫可以是巢狀的;所需的呼叫 Unlock 數相等。

陣列在鎖定時無法刪除。

COle保管庫Array：：operator LPCVARIANT

呼叫這個轉換運算子，以存取這個 COleSafeArray 物件的基礎 VARIANT 結構。

operator LPCVARIANT() const;

COle保管庫Array：：operator LPVARIANT

呼叫這個轉換運算子，以存取這個 COleSafeArray 物件的基礎 VARIANT 結構。

operator LPVARIANT();

備註

請注意，變更此函式所傳回之指標所存取之 結構中的 VARIANT 值，將會變更這個 COleSafeArray 物件的值。

COle保管庫Array：：operator =

這些多載指派運算子會將來源值複製到這個 COleSafeArray 物件中。

COleSafeArray& operator=(const COleSafeArray& saSrc);
COleSafeArray& operator=(const VARIANT& varSrc);
COleSafeArray& operator=(LPCVARIANT pSrc);
COleSafeArray& operator=(const COleVariant& varSrc);

備註

每個運算子的簡短描述如下：

• operator =（ saSrc ） 將現有的 COleSafeArray 物件複製到這個物件。

• operator =（ varSrc ） 將現有的 VARIANT 或 COleVariant 陣列複製到這個物件中。

• operator =（ pSrc） 將 pSrc 存取 的 VARIANT 陣列物件複製到這個物件。

COle保管庫Array：：operator ==

這個運算子會比較兩個數組 （ SAFEARRAY 、 VARIANTCOleVariant 或 COleSafeArray 陣列），如果陣列相等，則傳回非零值，否則為 0。

BOOL operator==(const SAFEARRAY& saSrc) const;  BOOL operator==(LPCSAFEARRAY pSrc) const;

BOOL operator==(const COleSafeArray& saSrc) const;  BOOL operator==(const VARIANT& varSrc) const;

BOOL operator==(LPCVARIANT pSrc) const;  BOOL operator==(const COleVariant& varSrc) const;

備註

如果兩個數組的維度數目相等、每個維度的大小相等，以及相等專案值，則兩個數組相等。

COleSafeArray::operator <<

插入 COleSafeArray （ << ） 運算子支援將物件診斷傾印和儲存 COleSafeArray 至封存。

CDumpContext& AFXAPI operator<<(
    CDumpContext& dc,
    COleSafeArray& saSrc);

COle保管庫Array：:P trOfIndex

傳回索引值所指定專案的指標。

void PtrOfIndex(
    long* rgIndices,
    void** ppvData);

參數

rgIndices
識別陣列專案的索引值陣列。 必須指定專案的所有索引。

ppvData
傳回時，指向 rgIndices 中 值所識別之專案的指標。

COle保管庫Array：:P utElement

將單一項目指派到陣列。

void PutElement(
    long* rgIndices,
    void* pvData);

參數

rgIndices
陣列的每個維度索引陣列的指標。

pvData
要指派給陣列的資料指標。 VT_DISPATCH、VT_UNKNOWN和VT_BSTR變體類型是指標，不需要另一層間接存取。

備註

此函式會在指派元素之前和之後，自動呼叫 Windows 函式保管庫ArrayLock 和 保管庫ArrayUnlock 。 如果資料項目是字串、物件或變數，函數會正確將它複製，而且如果現有的項目是字串、物件或變數，則會正確清除。

請注意，您可以在陣列中擁有多個鎖定，因此您可以在陣列由其他作業鎖定時將項目放入陣列。

發生錯誤時，函式會 擲回 CMemoryException 或 COleException 。

範例

VARIANT retVariantArray()
{
   COleSafeArray saRet;
   DWORD numElements[] = { 10, 10 }; // 10x10

   // Create the 2 dimensional safe-array of type VT_R8 with size 10x10
   saRet.Create(VT_R8, 2, numElements);

   // Initialize safearray  with values...
   long index[2];
   for (index[0] = 0; index[0] < 10; index[0]++)
   {
      for (index[1] = 0; index[1] < 10; index[1]++)
      {
         double val = index[0] + index[1] * 10;
         //populate the safearray elements with double values
         saRet.PutElement(index, &val);
      }
   }
   // Return the safe-array encapsulated in a VARIANT...
   return saRet.Detach();
}

COle保管庫Array：：Redim

變更安全陣列的最小有效（最右邊）界限。

void Redim(SAFEARRAYBOUND* psaboundNew);

參數

psaboundNew
包含新陣列系結之新安全陣列系結結構的指標。 只能變更陣列最不重要的維度。

備註

發生錯誤時，函式會 擲回 COleException 。

COle保管庫Array：：ResizeOneDim

變更一維 COleSafeArray 物件中的專案數目。

void ResizeOneDim(DWORD dwElements);

參數

dwElements
一維安全陣列中的元素數目。

備註

發生錯誤時，函式會 擲回 COleException 。

範例

請參閱 COle保管庫Array：：CreateOneDim 的範例 。

COle保管庫Array：：UnaccessData

遞減陣列的鎖定計數，並使 所擷取的 AccessData 指標失效。

void UnaccessData();

備註

發生錯誤時，函式會 擲回 COleException 。

範例

請參閱 COle保管庫Array：：AccessData 的 範例。

COle保管庫Array：：Unlock

遞減陣列的鎖定計數，以便釋放或調整大小。

void Unlock();

備註

在陣列中的資料存取完成之後，會呼叫此函式。 發生錯誤時，它會擲回 COleException 。

另請參閱

階層架構圖表
COleVariant 類別
CRecordset 類別
CDatabase 類別