Класс COleSafeArray

Статья
10/12/2023

Класс для работы с массивами произвольных типов и измерений.

Синтаксис

class COleSafeArray : public tagVARIANT

Участники

Открытые конструкторы

Имя	Описание
COle Сейф Array::COle Сейф Array	Формирует объект `COleSafeArray`.

Открытые методы

Имя	Описание
COle Сейф Array::AccessData	Извлекает указатель на данные массива.
COle Сейф Array::AllocData	Выделяет память для массива.
COle Сейф Array::AllocDescriptor	Выделяет память для дескриптора безопасного массива.
COle Сейф Array::Attach	Предоставляет элемент управления существующим `VARIANT` массивом объекту `COleSafeArray` .
COle Сейф Array::Clear	Освобождает все данные в базовой `VARIANT`среде.
COle Сейф Array::Copy	Создает копию существующего массива.
COle Сейф Array::Create	Создает безопасный массив.
COle Сейф Array::CreateOneDim	Создает одномерный `COleSafeArray` объект.
COle Сейф Array::D etraits	Уничтожает существующий массив.
COle Сейф Array::D edata	Уничтожает данные в безопасном массиве.
COle Сейф Array::D escriptor	Уничтожает дескриптор безопасного массива.
COle Сейф Array::D etach	Отсоединяет массив VARIANT от `COleSafeArray` объекта (чтобы данные не были освобождены).
COle Сейф Array::GetByteArray	Копирует содержимое безопасного массива в CByteArray.
COle Сейф Array::GetDim	Возвращает число измерений в массиве.
COle Сейф Array::GetElement	Извлекает один элемент безопасного массива.
COle Сейф Array::GetElemSize	Возвращает размер в байтах одного элемента в безопасном массиве.
COle Сейф Array::GetLBound	Возвращает нижнюю границу для любого измерения безопасного массива.
COle Сейф Array::GetOneDimSize	Возвращает количество элементов в одномерном `COleSafeArray` объекте.
COle Сейф Array::GetUBound	Возвращает верхнюю границу для любого измерения безопасного массива.
COle Сейф Array::Lock	Увеличивает число блокировок массива и помещает указатель на данные массива в дескрипторе массива.
COle Сейф Array::P trOfIndex	Возвращает указатель на индексированные элементы.
COle Сейф Array::P utElement	Помещает в массив один элемент.
COle Сейф Array::Redim	Изменяет наименьшую значительную (правую) границу безопасного массива.
COle Сейф Array::ResizeOneDim	Изменяет количество элементов в одномерном `COleSafeArray` объекте.
COle Сейф Array::UnaccessData	Уменьшает количество блокировок массива и отменяет указатель, полученный с помощью `AccessData`.
COle Сейф Array::Unlock	Уменьшает количество блокировок массива, чтобы его можно было освободить или изменить.

Открытые операторы

Имя	Описание
COle Сейф Array::operator LPCVARIANT	Обращается к базовой `VARIANTCOleSafeArray` структуре объекта.
COle Сейф Array::operator LPVARIANT	Обращается к базовой `VARIANTCOleSafeArray` структуре объекта.
COle Сейф Array::operator =	Копирует значения в `COleSafeArray` объект (`SAFEARRAY`, или `VARIANTCOleVariantCOleSafeArray` массив).
COle Сейф Array::operator ==	Сравнивает два варианта массивов (`SAFEARRAY`, `VARIANTCOleVariantCOleSafeArray` или массивов).
`COleSafeArray::operator <<`	Выводит содержимое `COleSafeArray` объекта в контекст дампа.

Замечания

COleSafeArray производный от структуры OLE VARIANT . Функции-члены OLE SAFEARRAY доступны COleSafeArrayчерез набор функций-членов, специально предназначенных для одномерных массивов байтов.

Иерархия наследования

tagVARIANT

COleSafeArray

Требования

Заголовок: afxdisp.h

COle Сейф Array::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();
   }
}

COle Сейф Array::AllocData

Выделяет память для безопасного массива.

void AllocData();

Замечания

При ошибке функция создает исключение CMemoryException или COleException.

COle Сейф Array::AllocDescriptor

Выделяет память для дескриптора безопасного массива.

void AllocDescriptor(DWORD dwDims);

Параметры

dwDims
Количество измерений в безопасном массиве.

Замечания

При ошибке функция создает исключение CMemoryException или COleException.

COle Сейф Array::Attach

Предоставляет управление данными в существующем VARIANT массиве объекту COleSafeArray .

void Attach(VARIANT& varSrc);

Параметры

varSrc
Объект VARIANT. Параметр varSrc должен иметь VT_ARRAY VARTYPE.

Замечания

Тип источника VARIANTимеет значение VT_EMPTY. Эта функция очищает текущие данные массива, если таковые есть.

Пример

См. пример COle Сейф Array::AccessData.

COle Сейф Array::Clear

Очищает безопасный массив.

void Clear();

Замечания

Функция очищает безопасный массив, задав VARTYPE объект VT_EMPTY. Текущее содержимое освобождается и массив освобождается.

COle Сейф Array::COle Сейф Array

Формирует объект 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 объект или SAFEARRAY копируемый в новый COleSafeArray объект.

vtSrc
VARTYPE нового COleSafeArray объекта.

psaSrc
Указатель на копируемый SAFEARRAY в новый COleSafeArray объект.

varSrc
Существующий VARIANT объект или COleVariant объект, копируемый в новый COleSafeArray объект.

Psrc
Указатель на VARIANT объект, скопированный в новый COleSafeArray объект.

Замечания

Все эти конструкторы создают новые COleSafeArray объекты. Если нет параметра, создается пустой COleSafeArray объект (VT_EMPTY). Если файл COleSafeArray копируется из другого массива, тип VARTYPE которого известен неявно (илиCOleSafeArrayCOleVariantVARIANT), VARTYPE исходного массива сохраняется и не нужно указывать. Если файл COleSafeArray копируется из другого массива, тип VARTYPE которого не известен (SAFEARRAY), в параметре vtSrc необходимо указать VARTYPE.

При ошибке функция создает исключение CMemoryException или COleException.

COle Сейф Array::Copy

Создает копию существующего безопасного массива.

void Copy(LPSAFEARRAY* ppsa);

Параметры

ppsa
Указатель на расположение, в котором возвращается дескриптор нового массива.

Замечания

При ошибке функция создает исключение CMemoryException или COleException.

COle Сейф Array::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);

COle Сейф Array::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]);

COle Сейф Array::D etraits

Уничтожает существующий дескриптор массива и все данные в массиве.

void Destroy();

Замечания

Если объекты хранятся в массиве, каждый объект освобождается. При ошибке функция создает исключение CMemoryException или COleException.

COle Сейф Array::D edata

Уничтожает все данные в безопасном массиве.

void DestroyData();

Замечания

COle Сейф Array::D escriptor

Уничтожает дескриптор безопасного массива.

void DestroyDescriptor();

Замечания

При ошибке функция создает исключение CMemoryException или COleException.

COle Сейф Array::D etach

Отсоединяет VARIANT данные от COleSafeArray объекта.

VARIANT Detach();

Возвращаемое значение

Базовое VARIANTCOleSafeArray значение объекта.

Замечания

Функция отсоединяет данные в безопасном массиве, задав VARTYPE объекта на VT_EMPTY. Вызывающий объект несет ответственность за освобождение массива путем вызова функции Windows VariantClear.

При ошибке функция вызывает COleException.

Пример

См. пример COle Сейф Array::P utElement.

COle Сейф Array::GetByteArray

Копирует содержимое безопасного массива в объект CByteArray.

void GetByteArray(CByteArray& bytes);

Параметры

bytes
Ссылка на объект CByteArray .

COle Сейф Array::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);

COle Сейф Array::GetElement

Извлекает один элемент безопасного массива.

void GetElement(
    long* rgIndices,
    void* pvData);

Параметры

rgIndices
Указатель на массив индексов для каждого измерения массива.

pvData
Указатель на расположение для размещения элемента массива.

Замечания

Эта функция автоматически вызывает функции SafeArrayLock Windows и 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;
      }
   }
}

COle Сейф Array::GetElemSize

Извлекает размер элемента в объекте COleSafeArray .

DWORD GetElemSize();

Возвращаемое значение

Размер элементов безопасного массива в байтах.

COle Сейф Array::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);

COle Сейф Array::GetOneDimSize

Возвращает количество элементов в одномерном COleSafeArray объекте.

DWORD GetOneDimSize();

Возвращаемое значение

Количество элементов в одномерном безопасном массиве.

Пример

См. пример COle Сейф Array::CreateOneDim.

COle Сейф Array::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);

COle Сейф Array::Lock

Увеличивает число блокировок массива и помещает указатель на данные массива в дескриптор массива.

void Lock();

Замечания

При ошибке возникает исключение COleException.

Указатель в дескрипторе массива действителен до вызова Unlock . Lock Вызовы могут быть вложенными; требуется равное количество вызововUnlock.

Невозможно удалить массив во время блокировки.

COle Сейф Array::operator LPCVARIANT

Вызовите этот оператор приведения, чтобы получить доступ к базовой VARIANT структуре для этого COleSafeArray объекта.

operator LPCVARIANT() const;

COle Сейф Array::operator LPVARIANT

operator LPVARIANT();

Замечания

Обратите внимание, что изменение значения в VARIANT структуре, к которому обращается указатель, возвращаемый этой функцией, изменит значение этого COleSafeArray объекта.

COle Сейф Array::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) Копирует объект массива, VARIANT к которым обращается pSrc в этот объект.

COle Сейф Array::operator ==

Этот оператор сравнивает два массива (SAFEARRAY, или COleVariantVARIANTCOleSafeArray массивы) и возвращает ненулевое значение, если они равны; в противном случае — 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);

COle Сейф Array::P trOfIndex

Возвращает указатель на элемент, заданный значениями индекса.

void PtrOfIndex(
    long* rgIndices,
    void** ppvData);

Параметры

rgIndices
Массив значений индекса, определяющий элемент массива. Все индексы элемента должны быть указаны.

ppvData
При возврате указатель на элемент, определяемый значениями в rgIndices.

COle Сейф Array::P utElement

Помещает в массив один элемент.

void PutElement(
    long* rgIndices,
    void* pvData);

Параметры

rgIndices
Указатель на массив индексов для каждого измерения массива.

pvData
Указатель на данные, которые требуется поместить в массив. VT_DISPATCH, VT_UNKNOWN и VT_BSTR типы вариантов являются указателями и не требуют другого уровня косвенного обращения.

Замечания

Эта функция автоматически вызывает функции Windows Сейф ArrayLock и Сейф ArrayUnlock до и после назначения элемента. Если строка, объект или вариант являются элементом данных, функция выполняет правильное копирование, а если существующим элементом — правильное удаление.

Обратите внимание, для массива можно настроить несколько блокировок, поэтому вы можете поместить в него элементы, недоступные для других операций.

При ошибке функция создает исключение 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();
}

COle Сейф Array::Redim

Изменяет наименьшую значительную (правую) границу безопасного массива.

void Redim(SAFEARRAYBOUND* psaboundNew);

Параметры

psaboundNew
Указатель на новую структуру с привязкой к безопасному массиву, содержащую новую привязку массива. Может быть изменено только наименьшее значительное измерение массива.

Замечания

При ошибке функция вызывает COleException.

COle Сейф Array::ResizeOneDim

Изменяет количество элементов в одномерном COleSafeArray объекте.

void ResizeOneDim(DWORD dwElements);

Параметры

dwElements
Количество элементов в одномерном безопасном массиве.

Замечания

При ошибке функция вызывает COleException.

Пример

См. пример COle Сейф Array::CreateOneDim.

COle Сейф Array::UnaccessData

Уменьшает количество блокировок массива и отменяет указатель, полученный с помощью AccessData.

void UnaccessData();

Замечания

При ошибке функция вызывает COleException.

Пример

См. пример COle Сейф Array::AccessData.

COle Сейф Array::Unlock

Уменьшает количество блокировок массива, чтобы его можно было освободить или изменить.

void Unlock();

Замечания

Эта функция вызывается после завершения доступа к данным в массиве. При ошибке возникает исключение COleException.

См. также

Диаграмма иерархии
Класс COleVariant
Класс CRecordset
Класс CDatabase