Класс CComSafeArray

Этот класс представляет собой оболочку для SAFEARRAY структуры.

Синтаксис

template <typename T, VARTYPE _vartype = _ATL_AutomationType<T>::type>
class CComSafeArray

Параметры

T
Тип данных для сохранения в массиве.

Участники

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

Имя	Описание
CComSafeArray::CComSafeArray	Конструктор.
CComSafeArray::~CComSafeArray	Деструктор

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

Имя	Описание
CComSafeArray::Add	Добавляет в объект CComSafeArrayодин или несколько элементов или SAFEARRAY структуру.
CComSafeArray::Attach	Присоединяет структуру SAFEARRAY к объекту CComSafeArray .
CComSafeArray::CopyFrom	Копирует содержимое SAFEARRAY структуры в CComSafeArray объект.
CComSafeArray::CopyTo	Создает копию объекта CComSafeArray.
CComSafeArray::Create	Создает объект CComSafeArray.
CComSafeArray::Destroy	Уничтожает объект CComSafeArray .
CComSafeArray::Detach	Отсоединяет SAFEARRAY объект от CComSafeArray объекта.
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 структуры.

Замечания

CComSafeArray предоставляет оболочку для SAFEARRAY класса типов данных, что упрощает создание и управление одномерными массивами практически любого из поддерживаемых VARIANT типов.

CComSafeArray упрощает передачу массивов между процессами и обеспечивает дополнительную безопасность путем проверки значений индекса массива на соответствие верхней и нижней границам.

Нижняя граница CComSafeArray может начинаться с любого определенного пользователем значения. Однако нижняя граница массивов, доступ к которым осуществляется через C++, должна быть равна 0. В других языках, например Visual Basic, могут использоваться другие ограничивающие значения (например, от −10 до 10).

Используется CComSafeArray::Create для создания CComSafeArray объекта и CComSafeArray::Destroy его удаления.

Может CComSafeArray содержать следующее подмножество VARIANT типов данных:

VARTYPE	Description
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	указатель типа decimal
VT_VARIANT	указатель типа variant
VT_CY	Currency - тип данных

Требования

Заголовок.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

Добавляет в объект CComSafeArrayодин или несколько элементов или SAFEARRAY структуру.

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 объект не поддерживается. При добавлении существующего массива объектов оба массива должны содержать элементы одного типа.

Флаг bCopy учитывается, когда элементы типа BSTR или VARIANT добавляются в массив. Значение TRUE по умолчанию гарантирует, что новая копия создается из данных при добавлении элемента в массив.

CComSafeArray::Attach

Присоединяет структуру SAFEARRAY к объекту CComSafeArray .

HRESULT Attach(const SAFEARRAY* psaSrc);

Параметры

psaSrc
Указатель на структуру SAFEARRAY .

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

Возвращает успешность S_OK или ошибку HRESULT при сбое.

Замечания

Присоединяет структуру к объекту SAFEARRAYCComSafeArray , делая существующие 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 при сбое.

Замечания

CComSafeArray Объект можно создать из существующей SAFEARRAYBOUND структуры и количества измерений или указать количество элементов в массиве и нижней границе. Если к массиву требуется получить доступ из C++, нижняя граница должна быть 0. Другие языки могут разрешать другие значения нижней границы (например, Visual Basic поддерживает массивы с элементами с диапазоном, например –10–10).

CComSafeArray::Destroy

Уничтожает объект CComSafeArray .

HRESULT Destroy();

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

Возвращает успешность S_OK или ошибку HRESULT при сбое.

Замечания

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

CComSafeArray::Detach

Отсоединяет SAFEARRAY объект от CComSafeArray объекта.

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-like, первый элемент которого — номер 0 элемента. В случае ошибки, например, недопустимый аргумент измерения, этот метод вызывается AtlThrow с HRESULT описанием ошибки.

CComSafeArray::GetSafeArrayPtr

Возвращает адрес элемента данных m_psa .

LPSAFEARRAY* GetSafeArrayPtr() throw();

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

Возвращает указатель на CComSafeArray::m_psa элемент данных.

CComSafeArray::GetType

Возвращает тип данных, хранящихся в массиве.

VARTYPE GetType() const;

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

Возвращает тип данных, хранящихся в массиве, который может быть любым из следующих типов:

VARTYPE	Description
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	указатель типа decimal
VT_VARIANT	указатель типа variant
VT_CY	Currency - тип данных

CComSafeArray::GetUpperBound

Возвращает верхнюю границу любого измерения массива.

LONG GetUpperBound(UINT uDim = 0) const;

Параметры

uDim
Измерение массива, для которого требуется получить верхнюю границу. Если опущено, значение по умолчанию равно 0.

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

Возвращает верхнюю границу. Это значение включает в себя максимальный допустимый индекс для этого измерения.

Замечания

В случае ошибки, например, недопустимый аргумент измерения, этот метод вызывается AtlThrow с HRESULT описанием ошибки.

CComSafeArray::IsSizable

Проверяет, можно ли изменить размер объекта CComSafeArray .

bool IsSizable() const;

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

Возвращает TRUE значение, если CComSafeArray его можно изменить, 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;

Параметры

lIndex, nIndex
Номер индекса требуемого элемента в массиве.

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

Возвращает соответствующий элемент массива.

Замечания

Выполняет аналогичную функцию 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 при сбое.

Замечания

Флаг bCopy учитывается, когда элементы типа BSTR или VARIANT добавляются в массив. Значение TRUE по умолчанию гарантирует, что новая копия создается из данных при добавлении элемента в массив.

См. также

SAFEARRAY Тип данных
CComSafeArray::Create
CComSafeArray::Destroy
Общие сведения о классе