COleSafeArray 类

项目
10/16/2023

与任意类型和维度的数组一起使用的类。

语法

class COleSafeArray : public tagVARIANT

成员

公共构造函数

名称	描述
COleSafeArray::COleSafeArray	构造 `COleSafeArray` 对象。

公共方法

名称	描述
COleSafeArray::AccessData	检索指向数组数据的指针。
COleSafeArray::AllocData	为数组分配内存。
COleSafeArray::AllocDescriptor	为安全数组描述符分配内存。
COleSafeArray::Attach	向 `COleSafeArray` 对象提供对现有 `VARIANT` 数组的控制。
COleSafeArray::Clear	释放基础 `VARIANT` 中的所有数据。
COleSafeArray::Copy	创建现有数组的副本。
COleSafeArray::Create	创建安全数组。
COleSafeArray::CreateOneDim	创建一维 `COleSafeArray` 对象。
COleSafeArray::Destroy	销毁现有数组。
COleSafeArray::DestroyData	销毁安全数组中的数据。
COleSafeArray::DestroyDescriptor	销毁安全数组的描述符。
COleSafeArray::Detach	将 VARIANT 数组从 `COleSafeArray` 对象中拆离（以便数据不会被释放）。
COleSafeArray::GetByteArray	将安全数组的内容复制到 CByteArray 中。
COleSafeArray::GetDim	返回数组中的维数。
COleSafeArray::GetElement	检索安全数组的单个元素。
COleSafeArray::GetElemSize	返回安全数组中某个元素的大小（以字节为单位）。
COleSafeArray::GetLBound	返回安全数组任意维度的下限。
COleSafeArray::GetOneDimSize	返回一维 `COleSafeArray` 对象中的元素数。
COleSafeArray::GetUBound	返回安全数组任意维度的上限。
COleSafeArray::Lock	递增数组的锁计数，并在数组描述符中放置指向数组数据的指针。
COleSafeArray::PtrOfIndex	返回指向索引元素的指针。
COleSafeArray::PutElement	将单个元素分配到数组。
COleSafeArray::Redim	更改安全数组最低有效（最右边）的边界。
COleSafeArray::ResizeOneDim	更改一维 `COleSafeArray` 对象中的元素数。
COleSafeArray::UnaccessData	递减数组的锁计数，使 `AccessData` 检索的指针失效。
COleSafeArray::Unlock	递减数组的锁计数，以便将其释放或调整大小。

公共运算符

“属性”	描述
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。

另请参阅

层次结构图
 COleVariant 类
 CRecordset 类
 CDatabase 类