Класс COleSafeArray

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

Синтаксис

class COleSafeArray : public tagVARIANT

Участники

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

Имя	Описание
COleSafeArray::COleSafeArray	Формирует объект COleSafeArray.

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

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

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

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

Замечания

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

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

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

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

void Attach(VARIANT& varSrc);

Параметры

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

Замечания

Тип источника 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 объект или 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.

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::D etraits

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

void Destroy();

Замечания

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

COleSafeArray::D edata

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

void DestroyData();

Замечания

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

COleSafeArray::D escriptor

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

void DestroyDescriptor();

Замечания

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

COleSafeArray::D etach

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

VARIANT Detach();

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

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

Замечания

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

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

Пример

См. пример COleSafeArray ::P utElement.

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
Указатель на расположение для размещения элемента массива.

Замечания

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

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

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

operator LPCVARIANT() const;

COleSafeArray::operator LPVARIANT

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

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

COleSafeArray::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);

COleSafeArray::P trOfIndex

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

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

Параметры

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

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

COleSafeArray::P utElement

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

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