COleSafeArray 类
与任意类型和维度的数组一起使用的类。
语法
class COleSafeArray : public tagVARIANT
成员
公共构造函数
| 名称 | 描述 |
|---|---|
| COleSafeArray::COleSafeArray | 构造 COleSafeArray 对象。 |
公共方法
公共运算符
| “属性” | 描述 |
|---|---|
| COleSafeArray::operator LPCVARIANT | 访问 COleSafeArray 对象的基础 VARIANT 结构。 |
| COleSafeArray::operator LPVARIANT | 访问 COleSafeArray 对象的基础 VARIANT 结构。 |
| COleSafeArray::operator = | 将值复制到 COleSafeArray 对象（SAFEARRAY、VARIANT、COleVariant 或 COleSafeArray 数组）。 |
| COleSafeArray::operator == | 比较两个变体数组（SAFEARRAY、VARIANT、COleVariant 或 COleSafeArray 数组）。 |
COleSafeArray::operator << |
将 COleSafeArray 对象的内容输出到转储上下文。 |
备注
COleSafeArray 派生自 OLE VARIANT 结构。 可以通过 COleSafeArray 使用 OLE SAFEARRAY 成员函数，以及一组专门为字节的一维数组设计的成员函数。
继承层次结构
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
向 COleSafeArray 对象提供对现有 VARIANT 数组数据的控制。
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 对象中的现有 COleSafeArray 对象或 SAFEARRAY。
vtSrc
新 COleSafeArray 对象的 VARTYPE。
psaSrc
指向要复制到新 COleSafeArray 对象中的 SAFEARRAY 的指针。
varSrc
要复制到新 COleSafeArray 对象中的现有 VARIANT 或 COleVariant 对象。
pSrc
指向要复制到新 COleSafeArray 对象中的 VARIANT 对象的指针。
备注
所有这些构造函数都会创建新的 COleSafeArray 对象。 如果没有参数，则会创建空的 COleSafeArray 对象 (VT_EMPTY)。 如果从具有隐式已知 VARTYPE 的另一个数组（COleSafeArray、COleVariant 或 VARIANT）复制 COleSafeArray，则保留源数组的 VARTYPE，不需要指定。 如果从 VARTYPE 未知的其他数组 (SAFEARRAY) 复制 COleSafeArray，则必须在 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::Destroy
销毁现有数组描述符和数组中的所有数据。
void Destroy();
备注
如果对象存储在数组中，则会释放每个对象。 出现错误时，该函数将引发 CMemoryException 或 COleException。
COleSafeArray::DestroyData
销毁安全数组中的所有数据。
void DestroyData();
注解
如果对象存储在数组中，则会释放每个对象。 出现错误时，该函数将引发 CMemoryException 或 COleException。
COleSafeArray::DestroyDescriptor
销毁安全数组的描述符。
void DestroyDescriptor();
注解
出现错误时，该函数将引发 CMemoryException 或 COleException。
COleSafeArray::Detach
从 COleSafeArray 对象中拆离 VARIANT 数据。
VARIANT Detach();
返回值
COleSafeArray 对象中的基础 VARIANT 值。
注解
该函数通过将对象的 VARTYPE 设置为 VT_EMPTY 来拆离安全数组中的数据。 调用方负责通过调用 Windows 函数 VariantClear 来释放数组。
出现错误时，该函数将引发 COleException。
示例
请参阅 COleSafeArray::PutElement 的示例。
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
指向放置数组元素的位置的指针。
备注
该函数在检索元素前后自动调用 Windows 函数 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);
备注
每个运算符的简要说明如下：
运算符 =（saSrc） 将现有
COleSafeArray对象复制到此对象中。运算符 =（varSrc） 将现有
VARIANT或COleVariant数组复制到此对象中。运算符 =（pSrc） 将 pSrc 访问的
VARIANT数组对象复制到此对象中。
COleSafeArray::operator ==
此运算符比较两个数组（SAFEARRAY、VARIANT、COleVariant 或 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::PtrOfIndex
返回指向索引值指定的元素的指针。
void PtrOfIndex(
long* rgIndices,
void** ppvData);
参数
rgIndices
用于标识数组元素的索引值的数组。 必须指定元素的所有索引。
ppvData
返回时，指向由 rgIndices 中值所标识的元素的指针。
COleSafeArray::PutElement
将单个元素分配到数组。
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。
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈