`CComSafeArray` 類別

發行項
07/05/2024

這個類別是結構的 SAFEARRAY 包裝函式。

語法

template <typename T, VARTYPE _vartype = _ATL_AutomationType<T>::type>
class CComSafeArray

參數

T
陣列中儲存之資料的類型。

成員

公用建構函式

名稱	描述
`CComSafeArray::CComSafeArray`	建構函式。
`CComSafeArray::~CComSafeArray`	解構函式。

公用方法

名稱	描述
`CComSafeArray::Add`	將一或多個項目或 `SAFEARRAY` 結構加入至 `CComSafeArray`。
`CComSafeArray::Attach`	將 `SAFEARRAY` 結構附加至 `CComSafeArray` 物件。
`CComSafeArray::CopyFrom`	將結構`CComSafeArray`的內容`SAFEARRAY`複製到物件中。
`CComSafeArray::CopyTo`	建立 `CComSafeArray` 物件的複本。
`CComSafeArray::Create`	建立 `CComSafeArray` 物件。
`CComSafeArray::Destroy`	終結 `CComSafeArray` 物件。
`CComSafeArray::Detach`	從 `CComSafeArray` 物件卸離 `SAFEARRAY` 。
`CComSafeArray::GetAt`	從一維陣列中擷取單一項目。
`CComSafeArray::GetCount`	傳回陣列中的元素數目。
`CComSafeArray::GetDimensions`	傳回陣列中的維度數目。
`CComSafeArray::GetLowerBound`	傳回陣列中指定維度的下限。
`CComSafeArray::GetSafeArrayPtr`	傳回 `m_psa` 資料成員的位址。
`CComSafeArray::GetType`	傳回陣列中儲存之資料的類型。
`CComSafeArray::GetUpperBound`	傳回陣列中任何維度的上限。
`CComSafeArray::IsSizable`	測試是否可以調整 `CComSafeArray` 物件大小。
`CComSafeArray::MultiDimGetAt`	從多維陣列中擷取單一項目。
`CComSafeArray::MultiDimSetAt`	設定多維陣列中的項目值。
`CComSafeArray::Resize`	調整 `CComSafeArray` 物件大小。
`CComSafeArray::SetAt`	設定一維陣列中的項目值。

公用運算子

名稱	描述
`CComSafeArray::operator LPSAFEARRAY`	將值 `SAFEARRAY` 轉換成指標。
`CComSafeArray::operator[]`	從陣列中擷取項目。
`CComSafeArray::operator =`	指派運算子。

公用資料成員

名稱	描述
`CComSafeArray::m_psa`	此數據成員會保存結構的位址 `SAFEARRAY` 。

備註

CComSafeArray提供數據類型類別的SAFEARRAY包裝函式，因此建立和管理幾乎任何支援VARIANT類型的單維度和多維度數位相當簡單。

CComSafeArray 不僅簡化了在處理序之間傳遞陣列的作業，還藉由針對上下限檢查陣列索引值，來提供額外的安全性。

CComSafeArray 的下限開頭可以是任何使用者定義值；不過，透過 C++ 存取的陣列應該使用下限 0。 Visual Basic 等其他語言可能會使用其他界限值 (例如 -10 到 10)。

使用 CComSafeArray::Create 來建立 CComSafeArray 物件，並 CComSafeArray::Destroy 加以刪除。

CComSafeArray可以包含下列資料類型子VARIANT集：

`VARTYPE`	描述
`VT_I1`	`char`
`VT_I2`	`short`
`VT_I4`	`int`
`VT_I4`	`long`
`VT_I8`	`longlong`
`VT_UI1`	`byte`
`VT_UI2`	`ushort`
`VT_UI4`	`uint`
`VT_UI4`	`ulong`
`VT_UI8`	`ulonglong`
`VT_R4`	`float`
`VT_R8`	`double`
`VT_DECIMAL`	decimal 指標
`VT_VARIANT`	variant 指標
`VT_CY`	Currency 資料類型

需求

標頭： atlsafe.h

範例

// Create a multidimensional array, 
// then write and read elements

// Define an array of character pointers
CComSafeArray<char> *pSar;

char cElement;
char cTable[2][3] = {'A','B','C','D','E','F'};

// Declare the variable used to store the
// array indexes
LONG aIndex[2];

// Define the array bound structure
CComSafeArrayBound bound[2];
bound[0].SetCount(2);
bound[0].SetLowerBound(0);
bound[1].SetCount(3);
bound[1].SetLowerBound(0);   

// Create a new 2 dimensional array
// each dimension size is 3
pSar = new CComSafeArray<char>(bound,2); 

// Use MultiDimSetAt to store characters in the array
for (int x = 0; x < 2; x++)
{
   for (int y = 0; y < 3; y++)
   {
      aIndex[0] = x;
      aIndex[1] = y;
      HRESULT hr = pSar->MultiDimSetAt(aIndex,cTable[x][y]);
      ATLASSERT(hr == S_OK);
   }
}
// Use MultiDimGetAt to retrieve characters in the array
for (int x = 0; x < 2; x++)
{
   for (int y = 0; y < 3; y++)
   {
      aIndex[0]=x;
      aIndex[1]=y;
      HRESULT hr = pSar->MultiDimGetAt(aIndex,cElement);
      ATLASSERT(hr == S_OK);
      ATLASSERT(cElement == cTable[x][y]);
   }   
}

`CComSafeArray::Add`

將一或多個項目或 SAFEARRAY 結構加入至 CComSafeArray。

HRESULT Add(const SAFEARRAY* psaSrc);
HRESULT Add(ULONG ulCount, const T* pT, BOOL bCopy = TRUE);
HRESULT Add(const T& t, BOOL bCopy = TRUE);

參數

psaSrc
SAFEARRAY 物件的指標。

ulCount
要加入至陣列的物件數目。

pT
要加入至陣列之一或多個物件的指標。

t
要加入至陣列之對象的參考。

bCopy
指出是否應該建立數據的複本。預設值是 TRUE。

傳回值

S_OK傳回成功，或失敗時發生錯誤HRESULT。

備註

新的物件會附加至現有 SAFEARRAY 對象的結尾。不支援將物件新增至多維度 SAFEARRAY 物件。新增現有的物件陣列時，這兩個陣列都必須包含相同類型的元素。

當 bCopy 型別 BSTR 或 VARIANT 的專案新增至數位時，會考慮旗標。的預設值 TRUE 可確保當元素加入數位時，會建立數據的新複本。

`CComSafeArray::Attach`

將 SAFEARRAY 結構附加至 CComSafeArray 物件。

HRESULT Attach(const SAFEARRAY* psaSrc);

參數

psaSrc
結構的 SAFEARRAY 指標。

傳回值

S_OK傳回成功，或失敗時發生錯誤HRESULT。

備註

將 SAFEARRAY 結構附加至 CComSafeArray 物件，讓現有的 CComSafeArray 方法可供使用。

`CComSafeArray::CComSafeArray`

建構函式。

CComSafeArray();
CComSafeArray(const SAFEARRAYBOUND& bound);
CComSafeArray(ULONG  ulCount, LONG lLBound = 0);
CComSafeArray(const SAFEARRAYBOUND* pBound, UINT uDims = 1);
CComSafeArray(const CComSafeArray& saSrc);
CComSafeArray(const SAFEARRAY& saSrc);
CComSafeArray(const SAFEARRAY* psaSrc);

參數

bound
SAFEARRAYBOUND 結構。

ulCount
陣列中的項目數。

lLBound
下限值;也就是陣列中第一個專案的索引。

pBound
結構的指標 SAFEARRAYBOUND 。

uDims
陣列中的維度計數。

saSrc
結構或CComSafeArray對象的參考SAFEARRAY。不論是哪一種情況，建構函式都會使用此參考來建立數位的複本，因此在建構之後不會參考數位。

psaSrc
結構的指標 SAFEARRAY 。建構函式會使用此位址來建立數位的複本，因此在建構之後永遠不會參考數位。

備註

建立 CComSafeArray 物件。

`CComSafeArray::~CComSafeArray`

解構函式。

~CComSafeArray() throw()

備註

釋放所有已配置的資源。

`CComSafeArray::CopyFrom`

將結構CComSafeArray的內容SAFEARRAY複製到物件中。

HRESULT CopyFrom(LPSAFEARRAY* ppArray);

參數

ppArray
要複製的 SAFEARRAY 指標。

傳回值

S_OK傳回成功，或失敗時發生錯誤HRESULT。

備註

這個方法會將的內容 SAFEARRAY 複製到目前的 CComSafeArray 物件中。會取代數位的現有內容。

`CComSafeArray::CopyTo`

建立 CComSafeArray 物件的複本。

HRESULT CopyTo(LPSAFEARRAY* ppArray);

參數

ppArray
要在其中建立新 SAFEARRAY的位置指標。

傳回值

S_OK傳回成功，或失敗時發生錯誤HRESULT。

備註

這個方法會將對象SAFEARRAY的內容CComSafeArray複製到結構中。

`CComSafeArray::Create`

建立 CComSafeArray。

HRESULT Create(const SAFEARRAYBOUND* pBound, UINT uDims = 1);
HRESULT Create(ULONG ulCount = 0, LONG lLBound = 0);

參數

pBound
SAFEARRAYBOUND 物件的指標。

uDims
陣列中的維度數目。

搭配多維度陣列使用時，這個方法只會傳回特定維度中的元素數目。

`CComSafeArray::GetDimensions`

傳回陣列中的維度數目。

UINT GetDimensions() const;

傳回值

傳回陣列中的維度數目。

`CComSafeArray::GetLowerBound`

傳回陣列中指定維度的下限。

LONG GetLowerBound(UINT uDim = 0) const;

參數

uDim
要取得下限的陣列維度。如果省略，預設值為0。

傳回值

傳回下限。

備註

如果下限為 0，這表示第一個專案為元素數位 0 的 C 型陣列。例如，在發生錯誤時，這個方法會呼叫 AtlThrow ，並 HRESULT 描述錯誤。

`CComSafeArray::GetSafeArrayPtr`

傳回 m_psa 資料成員的位址。

LPSAFEARRAY* GetSafeArrayPtr() throw();

傳回值

傳回數據成員的 CComSafeArray::m_psa 指標。

`CComSafeArray::GetType`

傳回陣列中儲存之資料的類型。

VARTYPE GetType() const;

傳回值

傳回儲存在陣列中的數據類型，可以是下列任何類型：

`VARTYPE`	描述
`VT_I1`	`char`
`VT_I2`	`short`
`VT_I4`	`int`
`VT_I4`	`long`
`VT_I8`	`longlong`
`VT_UI1`	`byte`
`VT_UI2`	`ushort`
`VT_UI4`	`uint`
`VT_UI4`	`ulong`
`VT_UI8`	`ulonglong`
`VT_R4`	`float`
`VT_R8`	`double`
`VT_DECIMAL`	decimal 指標
`VT_VARIANT`	variant 指標
`VT_CY`	Currency 資料類型

`CComSafeArray::GetUpperBound`

傳回陣列中任何維度的上限。

LONG GetUpperBound(UINT uDim = 0) const;

參數

uDim
要取得上限的陣列維度。如果省略，預設值為0。

傳回值

傳回上限。這個值是內含的，這個維度的最大有效索引。

備註

例如，在發生錯誤時，這個方法會呼叫 AtlThrow ，並 HRESULT 描述錯誤。

`CComSafeArray::IsSizable`

測試是否可以調整 CComSafeArray 物件大小。

bool IsSizable() const;

傳回值

TRUE如果 CComSafeArray 可以重設大小，FALSE則傳回，如果無法重設大小則傳回。

`CComSafeArray::m_psa`

保留存取之 SAFEARRAY 結構的位址。

LPSAFEARRAY m_psa;

`CComSafeArray::MultiDimGetAt`

從多維陣列中擷取單一項目。

HRESULT MultiDimGetAt(const LONG* alIndex, T& t);

參數

alIndex
陣列中每個維度之索引向量的指標。最左邊的維度是 alIndex[0]。

t
傳回數據的參考。

傳回值

S_OK傳回成功，或失敗時發生錯誤HRESULT。

`CComSafeArray::MultiDimSetAt`

設定多維陣列中的項目值。

HRESULT MultiDimSetAt(const LONG* alIndex, const T& t);

參數

alIndex
陣列中每個維度之索引向量的指標。最右邊（最不重要）的維度是 alIndex[0]。

T
指定新元素的值。

傳回值

S_OK傳回成功，或失敗時發生錯誤HRESULT。

備註

這是的多維度版本 CComSafeArray::SetAt。

`CComSafeArray::operator []`

從陣列中擷取項目。

T& operator[](long lindex) const;
T& operator[](int nindex) const;

參數

lIndex, nIndex
陣列中必要專案的索引編號。

傳回值

傳回適當的陣列專案。

備註

執行與類似的函 CComSafeArray::GetAt式，不過這個運算符只適用於單一維度陣列。

`CComSafeArray::operator =`

指派運算子。

ATL::CComSafeArray<T>& operator=(const ATL::CComSafeArray& saSrc);
ATL::CComSafeArray<T>& operator=(const SAFEARRAY* psaSrc);

參數

saSrc
對 CComSafeArray 物件的參考。

psaSrc
SAFEARRAY 物件的指標。

傳回值

傳回陣列中儲存之資料的類型。

`CComSafeArray::operator LPSAFEARRAY`

將值 SAFEARRAY 轉換成指標。

operator LPSAFEARRAY() const;

傳回值

將值 SAFEARRAY 轉換成指標。

`CComSafeArray::Resize`

調整 CComSafeArray 物件大小。

HRESULT Resize(const SAFEARRAYBOUND* pBound);
HRESULT Resize(ULONG ulCount, LONG lLBound = 0);

參數

pBound
結構的指標 SAFEARRAYBOUND ，其中包含元素數目和陣列下限的相關信息。

ulCount
已重設大小陣列中要求的物件數目。

lLBound
下限。

傳回值

S_OK傳回成功，或失敗時發生錯誤HRESULT。

備註

這個方法只會調整最右邊的維度大小。它不會調整以傳回 IsResizable 的 FALSE陣列大小。

`CComSafeArray::SetAt`

設定一維陣列中的項目值。

HRESULT SetAt(LONG lIndex, const T& t, BOOL bCopy = TRUE);

參數

lIndex
要設定之陣列專案的索引編號。

t
指定專案的新值。

bCopy
指出是否應該建立數據的複本。預設值是 TRUE。

傳回值

S_OK傳回成功，或失敗時發生錯誤HRESULT。

備註

當 bCopy 型別 BSTR 或 VARIANT 的專案新增至數位時，會考慮旗標。的預設值 TRUE 可確保當元素加入數位時，會建立數據的新複本。

另請參閱

SAFEARRAY 數據類型
 CComSafeArray::Create
CComSafeArray::Destroy
類別概觀

共用方式為

CComSafeArray 類別

語法

參數

成員

公用建構函式

公用方法

公用運算子

公用資料成員

備註

需求

範例

CComSafeArray::Add

參數

傳回值

備註

CComSafeArray::Attach

參數

傳回值

備註

CComSafeArray::CComSafeArray

參數

備註

CComSafeArray::~CComSafeArray

備註

CComSafeArray::CopyFrom

參數

傳回值

備註

CComSafeArray::CopyTo

參數

傳回值

備註

CComSafeArray::Create

參數

傳回值

備註

CComSafeArray::Destroy

傳回值

備註

CComSafeArray::Detach

傳回值

備註

CComSafeArray::GetAt

參數

傳回值

CComSafeArray::GetCount

參數

傳回值

備註

CComSafeArray::GetDimensions

傳回值

CComSafeArray::GetLowerBound

參數

傳回值

備註

CComSafeArray::GetSafeArrayPtr

傳回值

CComSafeArray::GetType

傳回值

CComSafeArray::GetUpperBound

參數

傳回值

備註

CComSafeArray::IsSizable

傳回值

CComSafeArray::m_psa

CComSafeArray::MultiDimGetAt

參數

傳回值

CComSafeArray::MultiDimSetAt

參數

傳回值

備註

CComSafeArray::operator []

參數

傳回值

備註

CComSafeArray::operator =

參數

`CComSafeArray` 類別

`CComSafeArray::Add`

`CComSafeArray::Attach`

`CComSafeArray::CComSafeArray`

`CComSafeArray::~CComSafeArray`

`CComSafeArray::CopyFrom`

`CComSafeArray::CopyTo`

`CComSafeArray::Create`

`CComSafeArray::Destroy`

`CComSafeArray::Detach`

`CComSafeArray::GetAt`

`CComSafeArray::GetCount`

`CComSafeArray::GetDimensions`

`CComSafeArray::GetLowerBound`

`CComSafeArray::GetSafeArrayPtr`

`CComSafeArray::GetType`

`CComSafeArray::GetUpperBound`

`CComSafeArray::IsSizable`

`CComSafeArray::m_psa`

`CComSafeArray::MultiDimGetAt`

`CComSafeArray::MultiDimSetAt`

`CComSafeArray::operator []`

`CComSafeArray::operator =`

`CComSafeArray::operator LPSAFEARRAY`

`CComSafeArray::Resize`

`CComSafeArray::SetAt`