Дональд Бокс - Сущность технологии СОМ. Библиотека программиста

Синтаксис массива, приведенный в этом разделе, является совершенно разумным для программистов на С и C++. К сожалению, в то время, когда пишется этот текст, Visual Basic не способен работать ни с какими массивами переменной длины и может воспринимать только массивы фиксированной длины. Для того чтобы позволить Visual Basic посылать и получать массивы переменной длины, файлы СОМ IDL определяют среди прочих составной тип, именуемый SAFEARRAY. SAFEARRAY – это довольно редко используемая структура данных, которая позволяет передавать в качестве параметров многомерные массивы, совместимые с типом VARIANT. Для определения размеров массива SAFEARRAY в СОМ предусмотрен тип данных SAFEARRAYBOUND:

typedef struct tagSAFEARRAYBOUND {

ULONG cElements;

// size_is for dimension

// size_is для размерности

LONG lLbound;

// min index for dimension (usually 0)

// минимальный индекс для размерности (обычно 0)

} SAFEARRAYBOUND;

Тип данных SAFEARRAY внутри использует совместимый массив типа SAFEARRAYBOUND, чтобы придать некоторую форму содержимому массива:

typedef struct tagSAFEARRAY {

USHORT cDims;

// # of dimensions

// число измерений

USHORT fFeatures;

// flags describing contents

// флаги, описывающие содержимое

ULONG cbElements;

// # of bytes per element

// число байтов на элемент

ULONG cLocks;

// used to track memory usage

// применяется для слежения за использованием памяти

void* pvData;

// actual elements

// фактические элементы

[size_is(cDims)] SAFEARRAYBOUND rgsabound[]

} SAFEARRAY;

Приведенный выше IDL в действительности не используется для описания сетевого формата массивов SAFEARRAY, однако он используется для их программного описания.

Чтобы обеспечить пользователю максимальную гибкость в вопросах управления памятью, в СОМ определены следующие флаги, которые могут использоваться с полем fFeatures:

FADF_AUTO

/* array is allocated on the stack */

/* массив размещен в стеке */

FADF_STATIC

/* array is statically allocated */

/* массив размещен статически */

FADF_EMBEDDEO

/* array is embedded in a structure */

/* массив вложен в структуру */

FADF_FIXEDSIZE

/* may not be resized or reallocated */

/* не может изменить размеры или быть перемещен*/

FADF_BSTR

/* an array of BSTRs */

/* массив из BSTR */

FADF_UNKNOWN

/* an array of IUnknown* */

/* массив из IUnknown* */

FADF_DISPATCH

/* an array of IDispatch* */

/* массив из IDispatch* */

FADF_VARIANT

/* an array of VARIANTS */

/* массив из VARIANTS */

Для предоставления SAFEARRAY возможности определять типы данных своих элементов, компилятор IDL распознает специальный, специфический для SAFEARRAY, синтаксис:

HRESULT Method([in] SAFEARRAY(type) *ppsa);

где type – тип элемента в SAFEARRAY. Соответствующий прототип данного метода в C++ выглядел бы примерно так:

HRESULT Method(SAFEARRAY **psa);

Отметим, что в определении IDL используется только один уровень косвенности; в то же время в соответствующем определении C++ используются два уровня косвенности. Рассмотрим следующее определение на IDL, задающее массив типа SAFEARRAY из коротких целых чисел:

HRESULT Method([in] SAFEARRAY(short) *psa);

Соответствующее определение на Visual Basic выглядело бы таким образом:

Sub Method(ByVal psa As Integer())

Отметим, что в варианте на Visual Basic не указано явно размерностей массива. Напомним, однако, что Visual Basic поддерживает массивы с фиксированной длиной.

Тип данных SAFEARRAY поддерживается весьма богатым набором API-функций, которые позволяют изменять размерность массивов и производить обход их содержимого переносимым образом. Для доступа к элементам типа SAFEARRAY СОМ предусматривает следующие вызовы API-функций:

// get a pointer to the actual array elements

// получаем указатель на фактически элементы массива

HRESULT SafeArrayAccessData([in] SAFEARRAY *psa, [out] void ** ppv);

// release pointer returned by SafeArrayAccessData

// освобождаем указатель, возвращенный функцией SafeArrayAccessData

HRESULT SafeArrayUnaccessData([in] SAFEARRAY *psa);

// Get number of dimensions

// Получаем количество измерений

ULONG SafeArrayGetDim([in] SAFEARRAY *psa);

// Get upper bound of a dimension

// Получаем верхнюю границу измерения

HRESULT SafeArrayGetUBound([in] SAFEARRAY *psa, [in] UINT nDim, [out] long *pUBound);

// Get lower bound of a dimension

// Получаем нижнюю границу измерения

HRESULT SafeArrayGetLBound([in] SAFEARRAY *psa, [in] UINT nDim, [out] long *pLBound);

Эти методы обеспечивают компактный и надежный способ доступа к текущему содержимому массива. Рассмотрим следующий код на IDL:

HRESULT Sum([in] SAFEARRAY(long) *ppsa, [out, retval] long *pSum);

Тогда следующая реализация метода будет вычислять сумму элементов массива типа SAFEARRAY, состоящего из длинных целых чисел (long integers):

STDMETHODIMP MyClass::Sum(SAFEARRAY **ppsa, long *pnSum)

{

assert(ppsa && *ppsa && pnSum);

assert(SafeArrayGetDim(*ppsa) == 1);

long iUBound, iLBound;

// note that dimension indices are one-based

// отметим, что индексы размерности начинаются с единицы

HRESULT hr = SafeArrayGetUBound(*ppsa, 1, &iUBound);

assert(SUCCEEDED(hr));

hr = SafeArrayGetLBound(*ppsa, 1, &iLBound);

assert(SUCCEEDED(hr));

long *prgn = 0;

hr = SafeArrayAccessData(*ppsa, (void**)&prgn);

*pnSum = 0;

for (long i = 0; i < iUBound – iLBound; i++)

*pnSum += prgn[i];

SafeArrayUnaccessData(*ppsa);

return S_OK;

}

Отметим, что вызовы любых API-функций, которые имеют дело с размерностями массива, используют индексы, начинающиеся с единицы.

Приведенный выше фрагмент кода просто манипулировал содержимым существующего SAFEARRAY-массива. Для создания одномерного массива типа SAFEARRAY для передачи его в качестве параметра метода в СОМ имеется следующая API-функция, которая выделяет память для структуры SAFEARRAY и элементов этого массива в одном непрерывном блоке памяти:

SAFEARRAY *SafeArrayCreateVector(

[in] VARTYPE vt, // element type

// тип элемента

[in] long iLBound, // index of lower bound

// индекс нижней границы

[in] unsigned int cElems); // # of elements

// число элементов

Кроме того, в СОМ имеются различные функции, предназначенные для размещения многомерных массивов, однако их рассмотрение выходит за рамки данной дискуссии. При таком определении метода на IDL:

HRESULT GetPrimes([in] long nStart, [in] long nEnd, [out] SAFEARRAY(long) *ppsa);

следующее определение метода на C++ возвращает вызывающей программе массив типа SAFEARRAY, размещенный в вызываемом методе:

STDMETHODIMP MyClass::GetPrimes (long nMin, long nMax, SAFEARRAY **ppsa)

{

assert(ppsa);

UINT cElems = GetNumberOfPrimes(nMin, nMax);

*ppsa = SafeArrayCreateVector(VT_I4, 0, cElems);

assert(*ppsa);

long *prgn = 0;

HRESULT hr = SafeArrayAccessData(*ppsa, (void**)&prgn);

assert(SUCCEEDED(hr));

for (UINT i=0; i < cElems; i++)

prgn[i] = GetNextPrime(i ? prgn[1 – 1] : nMin);

SafeArrayUnaccessData(*ppsa);

return S_OK;

}

Соответствующий код с клиентской стороны выглядел бы на Visual Basic примерно так:

Function GetSumOfPrimes(ByVal nMin as Long, ByVal nMax as Long) as Long

Dim arr() as Long

Dim n as Variant

Objref.GetPrimes nMin, nMax, arr

GetSumOfPrimes = 0

for each n in arr

GetSumOfPrimes = GetSumOfPrimes + n

Next n

End Function

что соответствует следующему коду на C++:

long GetSumOfPrimes (long nMin, long nMax)

{

SAFEARRAY *pArray = 0;

HRESULT hr = g_pObjRef->GetPrimes(nMin, nMax, &pArray);

assert(SUCCEEDED(hr) && SafeArrayGetDim(pArray) == 1);

long *prgn = 0;

hr = SafeArrayAccessData(pArray, (void**)&prgn);

long iUBound, iLBound, result = 0;

SafeArrayGetUBound(pArray, 1, &iUBound);

SafeArrayGetLBound(pArray, 1, &iLBound);

for (long n = iLBound; n <= iUBound: n++)

result += prgn[n];

SafeArrayUnaccessData(pArray);

SafeArrayDestroy(pArray);

return n;

}

Отметим, что вызывающая программа ответственна за освобождение ресурсов, выделенных для SAFEARRAY-массива, возвращенного как [out]-параметр. Вызов функции SafeArrayDestroy корректно освобождает всю память и все ресурсы, удерживаемые структурой SAFEARRAY.