`CComSafeArray` 类

项目
04/03/2023

此类是 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`	将 `SAFEARRAY` 结构的内容复制到 `CComSafeArray` 对象中。
`CComSafeArray::CopyTo`	创建 `CComSafeArray` 对象的副本。
`CComSafeArray::Create`	创建一个 `CComSafeArray` 对象。
`CComSafeArray::Destroy`	销毁 `CComSafeArray` 对象。
`CComSafeArray::Detach`	将 `SAFEARRAY` 与 `CComSafeArray` 对象分离。
`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 data type 类提供包装器，从而可以轻松地创建并管理几乎所有支持 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`	十进制指针
`VT_VARIANT`	变体指针
`VT_CY`	货币数据类型

要求

标头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 对象添加到多维对象。添加现有对象数组时，两个数组必须包含相同类型的元素。

将 BSTR 或 VARIANT 类型的元素添加到数组时会考虑 bCopy 标志。 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
对 SAFEARRAY 结构或 CComSafeArray 对象的引用。在任何一种情况下，构造函数都使用此引用来制作数组的副本，因此在构造后不会引用该数组。

psaSrc
指向 SAFEARRAY 结构的指针。构造函数使用此地址来生成数组的副本，因此在构造后永远不会引用该数组。

注解

创建一个 CComSafeArray 对象。

`CComSafeArray::~CComSafeArray`

析构函数。

~CComSafeArray() throw()

注解

释放所有已分配的资源。

`CComSafeArray::CopyFrom`

将 SAFEARRAY 结构的内容复制到 CComSafeArray 对象中。

HRESULT CopyFrom(LPSAFEARRAY* ppArray);

参数

ppArray
指针，指向要复制的 SAFEARRAY。

返回值

成功时返回 S_OK，失败时返回错误 HRESULT。

注解

此方法将 SAFEARRAY 的内容复制到当前 CComSafeArray 对象中。将替换数组的现有内容。

`CComSafeArray::CopyTo`

创建 CComSafeArray 对象的副本。

HRESULT CopyTo(LPSAFEARRAY* ppArray);

参数

ppArray
指向要在其中创建新 SAFEARRAY 的位置的指针。

返回值

成功时返回 S_OK，失败时返回错误 HRESULT。

备注

此方法将 CComSafeArray 对象的内容复制到 SAFEARRAY 结构中。

`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。

注解

可以从现有 SAFEARRAYBOUND 结构和维数创建 CComSafeArray 对象，或者通过指定数组中的元素数和下限来创建对象。如果要从 C++ 访问数组，则下限应为 0。其他语言可能允许下限使用其他值（例如，Visual Basic 支持包含范围为 -10 到 10 的元素的数组）。

`CComSafeArray::Destroy`

销毁 CComSafeArray 对象。

HRESULT Destroy();

返回值

成功时返回 S_OK，失败时返回错误 HRESULT。

备注

销毁现有 CComSafeArray 对象及其包含的所有数据。

`CComSafeArray::Detach`

将 SAFEARRAY 与 CComSafeArray 对象分离。

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，则表示一个类似 C 的数组，其第一个元素是元素编号 0。如果发生错误，例如无效的尺寸参数，此方法调用 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`	十进制指针
`VT_VARIANT`	变体指针
`VT_CY`	货币数据类型

`CComSafeArray::GetUpperBound`

返回数组任意维度的上限。

LONG GetUpperBound(UINT uDim = 0) const;

参数

uDim
要获取其上限的数组维度。如果省略，则默认值为 0。

返回值

返回上限。也包括该值，该维度的最大有效索引。

备注

如果发生错误，例如无效的尺寸参数，此方法调用 AtlThrow 并通过 HRESULT 描述错误。

`CComSafeArray::IsSizable`

测试是否可重设 CComSafeArray 对象的大小。

bool IsSizable() const;

返回值

如果 CComSafeArray 可以调整大小，则返回 TRUE，如果无法调整大小，则返回 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。

备注

将 BSTR 或 VARIANT 类型的元素添加到数组时会考虑 bCopy 标志。 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`