COleSafeArray 類別

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

語法

class COleSafeArray : public tagVARIANT

成員

公用建構函式

名稱	描述
COleSafeArray：：COleSafeArray	建構 COleSafeArray 物件。

公用方法

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

公用運算子

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

備註

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

繼承階層架構

tagVARIANT

COleSafeArray

需求

標頭： afxdisp.h

COleSafeArray：：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();
   }
}

COleSafeArray：：AllocData

配置安全陣列的記憶體。

void AllocData();

備註

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

COleSafeArray：：AllocDescriptor

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

void AllocDescriptor(DWORD dwDims);

參數

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

備註

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

COleSafeArray：：Attach

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

void Attach(VARIANT& varSrc);

參數

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

備註

來源 VARIANT的類型會設定為 VT_EMPTY。 如果有任何，此函式會清除目前的數位數據。

範例

請參閱 COleSafeArray：：AccessData 的範例。

COleSafeArray：：Clear

清除安全陣列。

void Clear();

備註

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

COleSafeArray：：COleSafeArray

建構 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。

COleSafeArray：：Copy

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

void Copy(LPSAFEARRAY* ppsa);

參數

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

備註

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

COleSafeArray：：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);

COleSafeArray：：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]);

COleSafeArray：:D estroy

終結現有的陣列描述元和陣列中的所有數據。

void Destroy();

備註

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

COleSafeArray：:D estroyData

終結安全陣列中的所有數據。

void DestroyData();

備註

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

COleSafeArray：:D estroyDescriptor

終結安全陣列的描述項。

void DestroyDescriptor();

備註

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

COleSafeArray：:D etach

從 VARIANT 物件中斷鏈接數據 COleSafeArray 。

VARIANT Detach();

傳回值

物件中COleSafeArray的基礎VARIANT值。

備註

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

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

範例

請參閱 COleSafeArray：:P utElement 的範例。

COleSafeArray：：GetByteArray

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

void GetByteArray(CByteArray& bytes);

參數

bytes
CByteArray 對象的參考。

COleSafeArray：：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);

COleSafeArray：：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;
      }
   }
}

COleSafeArray：：GetElemSize

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

DWORD GetElemSize();

傳回值

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

COleSafeArray：：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);

COleSafeArray：：GetOneDimSize

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

DWORD GetOneDimSize();

傳回值

一維安全陣列中的項目數目。

範例

請參閱 COleSafeArray：：CreateOneDim 的範例。

COleSafeArray：：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);

COleSafeArray：：Lock

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

void Lock();

備註

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

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

陣列在鎖定時無法刪除。

COleSafeArray：：operator LPCVARIANT

呼叫這個轉換運算符，以存取這個COleSafeArray對象的基礎VARIANT結構。

operator LPCVARIANT() const;

COleSafeArray：：operator LPVARIANT

呼叫這個轉換運算符，以存取這個COleSafeArray對象的基礎VARIANT結構。

operator LPVARIANT();

備註

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

COleSafeArray：：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陣列物件複製到這個物件。

COleSafeArray：：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);

COleSafeArray：:P trOfIndex

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

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

參數

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

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

COleSafeArray：:P utElement

將單一項目指派到陣列。

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

參數

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

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

備註

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

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

發生錯誤時，函式會 擲回 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();
}

COleSafeArray：：Redim

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

void Redim(SAFEARRAYBOUND* psaboundNew);

參數

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

備註

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

COleSafeArray：：ResizeOneDim

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

void ResizeOneDim(DWORD dwElements);

參數

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

備註

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

範例

請參閱 COleSafeArray：：CreateOneDim 的範例。

COleSafeArray：：UnaccessData

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

void UnaccessData();

備註

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

範例

請參閱 COleSafeArray：：AccessData 的範例。

COleSafeArray：：Unlock

遞減數位的鎖定計數，以便釋放或重設大小。

void Unlock();

備註

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

另請參閱

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