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 SAFEARRAY 结构的内容复制到 CComSafeArray 对象中。
CComSafeArray::CopyTo 创建 CComSafeArray 对象的副本。
CComSafeArray::Create 创建一个 CComSafeArray 对象。
CComSafeArray::Destroy 销毁 CComSafeArray 对象。
CComSafeArray::Detach SAFEARRAYCComSafeArray 对象分离。
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 结构的地址。

备注

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

BSTRVARIANT 类型的元素添加到数组时会考虑 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

SAFEARRAYCComSafeArray 对象分离。

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;

参数

%>
数组中所需元素的索引号。

返回值

返回适当的数组元素。

备注

执行与 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

备注

BSTRVARIANT 类型的元素添加到数组时会考虑 bCopy 标志。 TRUE 的默认值可确保在将元素添加到数组时对数据生成新副本。

另请参阅

SAFEARRAY 数据类型
CComSafeArray::Create
CComSafeArray::Destroy
类概述