CComSafeArray 類別
這個類別是 結構的 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
陣列中的維度數目。
ulCount
陣列中的項目數。
lLBound
下限值;也就是陣列中第一個專案的索引。
傳回值
S_OK傳回成功，或失敗時發生錯誤 HRESULT 。
備註
CComSafeArray物件可以從現有的 SAFEARRAYBOUND 結構和維度數目建立，或藉由指定陣列和下限中的專案數目來建立。 如果要從 C++ 存取陣列，下限應該是 0。 其他語言可能會允許下限的其他值（例如，Visual Basic 支援具有 -10 到 10 等範圍之元素的陣列。
CComSafeArray::Destroy
終結 CComSafeArray 物件。
HRESULT Destroy();
傳回值
S_OK傳回成功，或失敗時發生錯誤 HRESULT 。
備註
終結現有的 CComSafeArray 物件及其包含的所有資料。
CComSafeArray::Detach
從 CComSafeArray 物件卸離 SAFEARRAY 。
LPSAFEARRAY Detach();
傳回值
傳回 物件的指標 SAFEARRAY 。
備註
這個方法會將 SAFEARRAY 物件與 CComSafeArray 物件中斷連結。
CComSafeArray::GetAt
從一維陣列中擷取單一項目。
T& GetAt(LONG lIndex) const;
參數
lIndex
要傳回之陣列中值的索引編號。
傳回值
傳回必要陣列專案的參考。
CComSafeArray::GetCount
傳回陣列中的元素數目。
ULONG GetCount(UINT uDim = 0) const;
參數
uDim
陣列維度。
傳回值
傳回陣列中的元素數目。
備註
搭配多維度陣列使用時，這個方法只會傳回特定維度中的元素數目。
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
類別概觀
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應