Страница:
HRESULT IIDFromHWND(HWND hwnd, IID& riid)
{
TCHAR szEditText[1024];
GetWindowText(hwnd, szEditText, 1024);
#ifdef UNICODE return IIDFromString(szEditText, &riid);
#else OLECHAR wszEditText[l024];
ustrncpy(wszEditText, szEditText, 1024);
return IIDFromString(wszEditText, &riid);
#endif
}
Хотя этот фрагмент и генерирует оптимальный код, очень утомительно применять эту технику всякий раз, когда символьный параметр имеет неверный тип. Можно справиться с этой проблемой, если использовать промежуточный (shim) класс с конструктором, принимающим в качестве параметра любой тип символьной строки. Этот промежуточный класс должен также содержать в себе операторы приведения типа, что позволит использовать его в обоих случаях: когда ожидается const char * или const wchar_t *. В этих операциях приведения промежуточный класс либо выделяет резервный буфер и производит необходимое преобразование, либо просто возвращает исходную строку, если преобразования не требовалось. Деструктор промежуточного класса может затем освободить все выделенные буферы. Заголовочный файл ustring.h содержит два таких промежуточных класса: _U и _UNCC. Первый предназначен для нормального использования; второй используется с функциями и методами, тип аргументов которых не включает спецификатора const[2] (таких как IIDFromString). При возможности применения двух промежуточных классов предыдущий фрагмент кода может быть значительно упрощен:
HRESULT IIDFromHWND(HWND hwnd, IID& riid)
{
TCHAR szEditText[1024];
GetWindowText(hwnd, szEditText, 1024);
// use _UNCC shim class to convert if necessary
// используем для преобразования промежуточный класс _UNCC,
// если необходимо
return IIDFromString(_UNCC(szEditText), &riid);
}
Заметим, что не требуется никакой условной компиляции. Если код скомпилирован с версией Win32 с поддержкой Unicode, то класс _UNCC просто пропустит исходный буфер через свой оператор приведения типа. Если же код компилируется с версией Win32, не поддерживающей Unicode, то класс _UNCC выделит буфер и преобразует строку в Unicode. Затем деструктор _UNCC освободит буфер, когда операция будет выполнена полностью[3].
Следует обсудить еще один дополнительный тип данных, связанный с текстом, – BSTR. Строковый тип BSTR нужно применять во всех интерфейсах, которые предполагается использовать из языков Visual Basic или Java. Строки BSTR являются OLECHAR-строками с префиксом длины (length-prefix) в начале строки и нулем в ее конце. Префикс длины показывает число байт, содержащихся в строке (исключая завершающий нуль) и записан в форме четырехбайтового целого числа, непосредственно предшествующего первому символу строки. Рисунок 2.7 демонстрирует BSTR на примере строки «Hi». Чтобы позволить методам свободно возвращать строки BSTR без заботы о выделении памяти, все BSTR размещены с помощью распределителя памяти, управляемого СОМ. В СОМ предусмотрено несколько API-функций для управления BSTR:
// from oleauto.h
// allocate and initialize a BSTR
// выделяем память и инициализируем строку BSTR
BSTR SysAllocString(const OLECHAR *psz);
BSTR SysAllocStringLen(const OLECHAR *psz, UINT cch);
// reallocate and initialize a BSTR
// повторно выделяем память и инициализируем BSTR
INT SysReAllocString(BSTR *pbstr, const OLECHAR *psz);
INT SysReAllocStringLen(BSTR *pbstr, const OLECHAR * psz, UINT cch);
// free a BSTR
// освобождаем BSTR void SysFreeString(BSTR bstr);
// peek at length-prefix as characters or bytes
// считываем префикс длины как число символов или байт
UINT SysStringLen(BSTR bstr);
UINT SysStringByteLen(BSTR bstr);
При пересылке строк методу в качестве параметров типа [in] вызывающий объект должен заботиться о том, чтобы вызвать SysAllocString прежде, чем запускать сам метод, и чтобы вызвать SysFreeString после того, как метод закончил работу. Рассмотрим следующее определение метода:
HRESULT SetString([in] BSTR bstr);
Пусть в вызывающей программе уже имеется строка, совместимая с OLECHAR, тогда для того, чтобы преобразовать строку в BSTR до вызова метода, необходимо следующее:
// convert raw OLECHAR string to a BSTR
// преобразовываем «сырую» строку OLECHAR в строку BSTR
BSTR bstr = SysAllocString(OLESTR(«Hello»));
// invoke method
// вызываем метод HRESULT hr = p->SetString(bstr);
// free BSTR
// освобождаем BSTR SysFreeString(bstr);
Промежуточный класс для работы с BSTR, _UBSTR, включен в заголовочный файл ustring.h:
// from ustring.h (book-specific header file)
// из ustring.h (специфический для данной книги заголовочный файл)
class _UBSTR
{
BSTR m_bstr;
public:
_UBSTR(const char *psz) : m_bstr(SysAllocStringLen(0, strlen(psz)))
{
mbstowcs(m_bstr, psz, INT_MAX);
}
_UBSTR(const wchar_t *pwsz) : m_bstr(SysAllocString(pwsz))
{
}
operator BSTR (void) const
{ return m_bstr; }
~_UBSTR(void)
{ SysFreeString(m_bstr); }
};
При наличии такого промежуточного класса предыдущий фрагмент кода значительно упростится:
// invoke method
// вызываем метод
HRESULT hr = p->SetString(_UBSTR(OLESTR(«Hello»)));
Заметим, что в промежуточном классе UBSTR могут быть в равной степени использованы строки типов char и wchar_t.
При передаче из метода строк через параметры типа [out] объект обязан вызвать SysAllocString, чтобы записать результирующую строку в буфер. Затем вызывающий объект должен освободить буфер путем вызова SysFreeString. Рассмотрим следующее определение метода:
HRESULT GetString([out, retval] BSTR *pbstr);
При реализации метода потребуется создать новую BSTR-строку для возврата вызывающему объекту:
STDMETHODIMP MyClass::GetString(BSTR *pbstr)
{
*pbstr = SysAllocString(OLESTR(«Coodbye!»)) ;
return S_OK;
}
Теперь вызывающий объект должен освободить строку сразу после того, как она скопирована в управляемый приложением строковый буфер:
extern OLECHAR g_wsz[];
BSTR bstr = 0;
HRESULT hr = p->GetString(&bstr);
if (SUCCEEDED(hr))
{
wcscpy(g_wsz, bstr); SysFreeString(bstr);
}
Тут нужно рассмотреть еще один важный аспект BSTR. В качестве BSTR можно передать нулевой указатель, чтобы указать на пустую строку. Это означает, что предыдущий фрагмент кода не совсем корректен. Вызов wcscpy:
wcscpy(g_wsz, bstr);
должен быть защищен от возможных нулевых указателей:
wcscpy (g_wsz, bstr ? bstr : OLESTR(""));
Для упрощения использования BSTR в заголовочном файле ustring.h содержится простая встраиваемая функция:
intline OLECHAR *SAFEBSTR(BSTR b)
{
return b ? b : OLESTR("");
}
Разрешение использовать нулевые указатели в качестве BSTR делает тип данных более эффективным с точки зрения использования памяти, хотя и приходится засорять код этими простыми проверками.
Простые типы, показанные на рис. 2.6, могут компоноваться вместе с применением структур языка С. IDL подчиняется правилам С для пространства имен тегов (tag namespace). Это означает, что большинство IDL-определений интерфейсов либо используют операторы определения типа (typedef):
typedef struct tagCOLOR
{
double red;
double green;
double blue;
} COLOR;
HRESULT SetColor([in] const COLOR *pColor);
либо должны использовать ключевое слово struct для квалификации имени тега:
struct COLOR { double red; double green; double blue; };
HRESULT SetColor([in] const struct COLOR *pColor);
Первый вариант предпочтительней. Простые структуры, подобные приведенной выше, можно использовать как из Visual Basic, так и из Java. Однако в то время, когда пишется эта книга, текущая версия Visual Basic может обращаться только к интерфейсам, использующим структуры, но она не может быть использована для реализации интерфейсов, в которых структуры являются параметрами методов.
IDL и СОМ поддерживают также объединения (unions). Для обеспечения однозначной интерпретации объединения IDL требует, чтобы в этом объединении имелся дискриминатор (discriminator), который показывал бы, какой именно член объединения используется в данный момент. Этот дискриминатор должен быть целого типа (integral type) и должен появляться на том же логическом уровне, что и само объединение. Если объединение объявлено вне области действия структуры, то оно считается неинкапсулированным (nonencapsulated):
union NUMBER
{
[case(1)] long i;
[case(2)] float f;
};
Атрибут [case] применен для установления соответствия каждого члена объединения своему дискриминатору. Для того чтобы связать дискриминатор с неинкапсулированным объединением, необходимо применить атрибут [switch_is]:
HRESULT Add([in, switch_is(t)] union NUMBER *pn, [in] short t);
Если объединение заключено вместе со своим дискриминатором в окружающую структуру, то этот составной тип (aggregate type) называется инкапсулированным, или размеченным объединением (discriminated union):
struct UNUMBER
{ short t; [switch_is(t)]
union VALUE
{
[case(1)] long i;
[case(2)] float f;
};
};
СОМ предписывает для использования с Visual Basic одно общее размеченное объединение. Это объединение называется VARIANT[4] и может хранить объекты или ссылки на подмножество базовых типов, поддерживаемых IDL. Каждому из поддерживаемых типов присвоено соответствующее значение дискриминатора:
VT_EMPTY nothing
VT_NULL SQL style Null
VT_I2 short
VT_I4 long
VT_R4 float
VT_R8 double
VT_CY CY (64-bit currency)
VT_DATE DATE (double)
VT_BSTR BSTR
VT_DISPATCH IDispatch *
VT_ERROR HRESULT
VT_BOOL VARIANT_BOOL (True=-1, False=0)
VT_VARIANT VARIANT *
VT_UNKNOWN IUnknown *
VT_DECIMAL 16 byte fixed point
VT_UI1 opaque byte
Следующие два флага можно использовать в сочетании с вышеприведенными тегами, чтобы указать, что данный вариант (variant) содержит ссылку или массив данного типа:
VT_ARRAY Указывает, что вариант содержит массив SAFEARRAY
VT_BYREF Указывает, что вариант является ссылкой
СОМ предлагает несколько API-функций для управления VARIANT:
// initialize a variant to empty
// обнуляем вариант
void VariantInit(VARIANTARG * pvarg);
// release any resources held in a variant
// освобождаем все ресурсы, используемые в варианте
HRESULT VariantClear(VARIANTARG * pvarg);
// deep-copy one variant to another
// полностью копируем один вариант в другой
HRESULT VariantCopy(VARIANTARG * plhs, VARIANTARG * prhs);
// dereference and deep-copy one variant into another
// разыменовываем и полностью копируем один вариант в другой
HRESULT VariantCopyInd(VARIANT * plhs, VARIANTARG * prhs);
// convert a variant to a designated type
// преобразуем вариант к указанному типу
HRESULT VariantChangeType(VARIANTARG * plhs, VARIANTARG * prhs, USHORT wFlags, VARTYPE vtlhs);
// convert a variant to a designated type
// преобразуем вариант к указанному типу (с явным указанием кода локализации)
HRESULT VariantChangeTypeEx(VARIANTARG * plhs, VARIANTARG * prhs, LCID lcid, USHORT wFlags, VARTYPE vtlhs);
Эти функции значительно упрощают управление VARIANT'ами. Чтобы понять, как используются эти API-функции, рассмотрим метод, принимающий VARIANT в качестве [in]-параметра:
HRESULT UseIt([in] VARIANT var);
Следующий фрагмент кода демонстрирует, как передать в этот метод целое число:
VARIANT var;
VariantInit(&var);
// initialize VARIANT
// инициализируем VARIANT
V_VT(&var) = VT_I4;
// set discriminator
// устанавливаем дискриминатор
V_I4(&var) = 100;
// set union
// устанавливаем объединение
HRESULT hr = pItf->UseIt(var);
// use VARIANT
// используем VARIANT
VariantClear(&var);
// free any resources in VARIANT
// освобождаем все ресурсы VARIANT
Отметим, что этот фрагмент кода использует макросы стандартного аксессора (accessor) для доступа к элементам данных VARIANT. Две следующие строки
V_VT(&var) = VT_I4;
V_I4(&var) = 100;
эквивалентны коду, который обращается к самим элементам данных:
var.vt = VT_I4;
var.lVal = 100;
Первый вариант предпочтительнее, так как он может компилироваться на С-трансляторах, которые не поддерживают неименованных объединений.
Ниже приведен пример того, как с помощью приведенной выше технологии реализация метода использует параметр VARIANT в качестве строки:
STDMETHODIMP MyClass::UseIt( /*[in] */ VARIANT var)
{
// declare and init a second VARIANT
// объявляем и инициализируем второй VARIANT
VARIANT var2;
VariantInit(&var2);
// convert var to a BSTR and store it in var2
// преобразуем переменную в BSTR и заносим ее в var2
HRESULT hr = VariantChangeType(&var2, &var, 0, VT_BSTR);
// use the string
// используем строку
if (SUCCEEDED(hr))
{
ustrcpy(m_szSomeDataMember, SAFEBSTR(V_BSTR(&var2)));
// free any resources held by var2
// освобождаем все ресурсы, поддерживаемые var2
VariantClear(&var2);
}
return hr;
}
Отметим, что API-процедура VariantChangeType способна осуществлять сложное преобразование любого переданного клиентом типа из VARIANT в нужный тип (в данном случае BSTR).
Один из последних типов данных, который вызывает дискуссию, – это интерфейс СОМ. Интерфейсы СОМ могут быть переданы в качестве параметров метода одним из двух способов. Если тип интерфейсного указателя известен на этапе проектирования, то тип интерфейса может быть объявлен статически:
HRESULT GetObject([out] IDog **ppDog);
Если же тип на этапе проектирования неизвестен, то разработчик интерфейса может дать пользователю возможность задать тип на этапе выполнения. Для поддержки динамически типизируемых интерфейсов в IDL имеется атрибут [iid_is]:
HRESULT GetObject([in] REFIID riid, [out, iid_is(riid)] IUnknown **ppUnk);
Хотя эта форма будет работать вполне хорошо, следующий вариант предпочтительнее из-за его подобия с QueryInterface:
HRESULT GetObject([in] REFIID riid, [out, iid_is(riid)] void **ppv);
Атрибут [iid_is] можно использовать как с параметрами [in], так и [out] для типов IUnknown * или void *. Для того чтобы использовать параметр интерфейса с динамически типизируемым типом, необходимо просто установить IID указателя требуемого типа:
IDog *pDog = 0; HRESULT hr = pItf->GetObject(IID_IDog, (void**)&pDog);
Соответствующая реализация для инициализации этого параметра просто использовала бы метод QueryInterface для нужного объекта:
STDMETHODIMP Class::GetObject(REFIID riid, void **ppv)
{
extern IUnknown * g_pUnkTheDog;
return g_pUnkTheDog->QueryInterface(riid, ppv);
}
Для уменьшения количества дополнительных вызовов методов между клиентом и объектом указатели интерфейса с динамически типизируемым типом должны всегда использоваться вместо указателей интерфейса со статически типизируемым типом IUnknown.
Атрибуты и свойства
Иногда бывает полезно показать, что объект имеет некие открытые свойства, которые могут быть доступны и/или которые можно модифицировать через СОМ-интерфейс. СОМ IDL позволяет аннотировать методы интерфейса с тем, чтобы данный метод либо модифицировал, либо читал именованный атрибут объекта. Рассмотрим такое определение интерфейса:
[ object, uuid(0BB3DAE1-11F4-11d1-8C84-0080C73925BA) ]
interface ICollie : IDog
{
// Age is a read-only property
// Age (возраст) – это свойство только для чтения
[propget] HRESULT Age([out, retval] long *pVal);
// HairCount is a read/write property
// HairCount (счетчик волос) – свойство для чтения/записи
[propget] HRESULT HairCount([out, retval] long *pVal);
[propput] HRESULT HairCount([in] long val);
// CurrentThought is a write-only property
// CurrentThought (текущая мысль) – свойство только для записи
[propput] HRESULT CurrentThought([in] BSTR val);
}
Использование атрибутов [propget] и [propput] информирует компилятор IDL, что методы, которые ему соответствуют, должны быть отображены в преобразователи свойств (property mutators) или в аксессоры на языках, явно поддерживающих свойства. Применительно к Visual Basic это означает, что элементами Age, HairCount и CurrentThought можно манипулировать, используя тот же синтаксис, как при обращении к элементам структуры:
Sub UseCollie(fido as ICollie)
fido.HairCount = fido.HairCount – (fido.Age * 1000)
fido.CurrentThought = «I wish I had a bone»
End Sub
С++-отображение этого интерфейса просто прибавляет к именам методов конструкции put или get, чтобы подсказать программисту, что обращение относится к свойству:
void UseCollie(ICollie *pFido)
{
long n1, n2;
HRESULT hr = pFido->getHairCount(&n1);
assert(SUCCEEDED(hr));
hr = pFido->getAge(&n2);
assert(SUCCEEDED(hr));
hr = pFido->putHairCount(n1 – (n2 * 1000)): assert(SUCCEEDED(hr));
BSTR bstr = SysAllocString(OLESTR(«I wish I had a bone»));
hr = pFido->putCurrentThought(bstr);
assert(SUCCEEDED(hr));
SysFreeString(bstr);
}
Хотя свойства напрямую не обеспечивают развития, они полезны для выполнения точных преобразований на те языки, которые их поддерживают[1].
[ object, uuid(0BB3DAE1-11F4-11d1-8C84-0080C73925BA) ]
interface ICollie : IDog
{
// Age is a read-only property
// Age (возраст) – это свойство только для чтения
[propget] HRESULT Age([out, retval] long *pVal);
// HairCount is a read/write property
// HairCount (счетчик волос) – свойство для чтения/записи
[propget] HRESULT HairCount([out, retval] long *pVal);
[propput] HRESULT HairCount([in] long val);
// CurrentThought is a write-only property
// CurrentThought (текущая мысль) – свойство только для записи
[propput] HRESULT CurrentThought([in] BSTR val);
}
Использование атрибутов [propget] и [propput] информирует компилятор IDL, что методы, которые ему соответствуют, должны быть отображены в преобразователи свойств (property mutators) или в аксессоры на языках, явно поддерживающих свойства. Применительно к Visual Basic это означает, что элементами Age, HairCount и CurrentThought можно манипулировать, используя тот же синтаксис, как при обращении к элементам структуры:
Sub UseCollie(fido as ICollie)
fido.HairCount = fido.HairCount – (fido.Age * 1000)
fido.CurrentThought = «I wish I had a bone»
End Sub
С++-отображение этого интерфейса просто прибавляет к именам методов конструкции put или get, чтобы подсказать программисту, что обращение относится к свойству:
void UseCollie(ICollie *pFido)
{
long n1, n2;
HRESULT hr = pFido->getHairCount(&n1);
assert(SUCCEEDED(hr));
hr = pFido->getAge(&n2);
assert(SUCCEEDED(hr));
hr = pFido->putHairCount(n1 – (n2 * 1000)): assert(SUCCEEDED(hr));
BSTR bstr = SysAllocString(OLESTR(«I wish I had a bone»));
hr = pFido->putCurrentThought(bstr);
assert(SUCCEEDED(hr));
SysFreeString(bstr);
}
Хотя свойства напрямую не обеспечивают развития, они полезны для выполнения точных преобразований на те языки, которые их поддерживают[1].
Исключения
СОМ имеет специфическую поддержку выбрасывания (throwing) исключительных ситуаций из реализации методов. Поскольку в языке C++ не существует двоичного стандарта для исключений, СОМ предлагает явные API-функции для выбрасывания и перехвата объектов СОМ-исключений:
// throw an exception
// возбуждаем исключения
HRESULT SetErrorInfo([in] ULONG reserved, //
m.b.z. [in] IErrorlnfo *pei);
// catch an exception
// перехватываем исключение
HRESULT GetErrorInfo([in] ULONG reserved, // m.b.z.
[out] IErrorInfo **ppei);
Процедура SetErrorInfo вызывается из реализации метода, чтобы связать объект исключения с текущим логическим потоком (logical thread)[1]. GetErrorInfo выбирает объект исключения из текущего логического потока и сбрасывает исключение, так что следующие вызовы GetErrorInfo возвратят SFALSE, показывая тем самым, что необработанных исключений нет. Как следует из приведенных ниже подпрограмм, объекты исключений должны поддерживать по крайней мере интерфейс IErrorInfo:
[ object, uuid(1CF2B120-547D-101B-8E65-08002B2BD119) ]
interface IErrorInfo: IUnknown
{
// get IID of interface that threw exception
// получаем IID того интерфейса, который возбудил исключение
HRESULT GetGUID([out] GUID * pGUID);
// get class name of object that threw exception
// получаем имя класса того объекта, который возбудил исключение
HRESULT GetSource([out] BSTR * pBstrSource);
// get human-readable description of exception
// получаем читабельное описание исключения
HRESULT GetDescription([out] BSTR * pBstrDescription);
// get WinHelp filename of documentation of error
// получаем имя файла WinHelp, содержащего документацию об ошибке
HRESULT GetHelpFile([out] BSTR * pBstrHelpFile);
// get WinHelp context ID for documentation of error
// получаем контекстный идентификатор WinHelp для документации ошибки
HRESULT GetHelpContext([out] DWORD * pdwHelpContext);
}
Специальные объекты исключений могут выбрать другие специфические для исключений интерфейсы в дополнение к IErrorInfo.
СОМ предусматривает по умолчанию реализацию IErrorInfo, которую можно создать с использованием API-функции СОМ CreateErrorInfo:
HRESULT CreateErrorInfo([out] ICreateErrorInfo **ppcei);
В дополнение к IErrorInfo объекты исключений по умолчанию открывают интерфейс ICreateErrorInfo, чтобы позволить пользователю инициализировать состояние нового исключения:
[ object, uuid(22F03340-547D-101B-8E65-08002B2BD119) ]
interface ICreateErrorInfo: IUnknown
{
// set IID of interface that threw exception
// устанавливаем IID интерфейс, который возбудил исключение
HRESULT SetGUID([in] REFGUID rGUID);
// set class name of object that threw exception
// устанавливаем классовое имя объекта, который возбудил исключение
HRESULT SetSource([in, string] OLECHAR* pwszSource);
// set human-readable description of exception
// устанавливаем читабельное описание исключения
HRESULT SetDescription([in, string] OLECHAR* pwszDesc);
// set WinHelp filename of documentation of error
// устанавливаем имя файла WinHelp, содержащего документацию об ошибке
HRESULT SetHelpFile([in, string] OLECHAR* pwszHelpFile);
// set WinHelp context ID for documentation of error
// устанавливаем идентификатор контекста WinHelp для документации ошибки
HRESULT SetHelpContext([in] DWORD dwHelpContext);
}
Заметим, что этот интерфейс просто позволяет пользователю заполнить объект исключения пятью основными атрибутами, доступными из интерфейса IErrorInfo.
Следующая реализация метода выбрасывает СОМ-исключение своему вызывающему объекту, используя объект исключений по умолчанию:
STDMETHODIMP PugCat::Snore(void)
{
if (this->IsAsleep())
// ok to perform operation?
// можно ли выполнять операцию?
return this->DoSnore();
//do operation and return
// выполняем операцию и возвращаемся
//otherwise create an exception object
// в противном случае создаем объект исключений
ICreateErrorInfo *рсеi = 0; HRESULT hr = CreateErrorInfo(&pcei);
assert(SUCCEEDED(hr));
// initialize the exception object
// инициализируем объект исключений
hr = pcei->SetGUID(IIDIPug);
assert(SUCCEEDED(hr));
hr = pcei->SetSource(OLESTR(«PugCat»));
assert(SUCCEEDED(hr));
hr = pcei->SetDescription(OLESTR("I am not asleep!"));
assert(SUCCEEDED(hr));
hr = pcei->SetHelpFile(OLESTR(«C:\\PugCat.hlp»));
assert(SUCCEEDED(hr));
hr = pcei->SetHelpContext(5221);
assert(SUCCEEDED(hr));
// «throw» exception
// «выбрасываем» исключение
IErrorInfo *pei = 0;
hr = pcei->QueryInterface(IIDIErrorInfo, (void**)&pei);
assert(SUCCEEDED(hr));
hr = SetErrorInfo(0, pei);
// release resources and return a SEVERITYERROR result
// высвобождаем ресурсы и возвращаем результат
// SEVERITYERROR (серьезность ошибки)
pei->Release();
pcei->Release();
return PUGEPUGNOTASLEEP;
}
Отметим, что поскольку объект исключений передается в процедуру SetErrorInfo, СОМ сохраняет ссылку на исключение до тех пор, пока оно не будет «перехвачено» вызывающим объектом, использующим GetErrorInfo.
Объекты, которые сбрасывают исключения СОМ, должны использовать интерфейс ISupportErrorInfo , чтобы показывать, какие интерфейсы поддерживают исключения. Этот интерфейс используется клиентами, чтобы установить, верный ли результат дает GetErrorInfo[2]. Этот интерфейс предельно прост:
[ object, uuid(DFOB3060-548F-101B-8E65-08002B2BD119) ]
interface ISupportErrorInfo: IUnknown
{
HRESULT InterfaceSupportsErrorInfo([in] REFIID riid);
}
Предположим, что класс PugCat, рассмотренный в этой главе, сбрасывает исключения из каждого поддерживаемого им интерфейса. Тогда его реализация будет выглядеть так:
STDMETHODIMP PugCat::InterfaceSupportsErrorInfo(REFIID riid)
{
if (riid == IIDIAnimal || riid == IIDICat || riid == IIDIDog || riid == IIDIPug) return SOK;
else return SFALSE;
}
Ниже приведен пример клиента, который надежно обрабатывает исключения, используя ISupportErrorInfo и GetErrorInfo:
void TellPugToSnore(/*[in]*/ IPug *pPug)
{
// call a method
// вызываем метод
HRESULT hr = pPug->Snore();
if (FAILED(hr))
{
// check to see if object supports СОМ exceptions
// проверяем, поддерживает ли объект исключения СОМ
ISupportErrorInfo *psei = 0;
HRESULT hr2 =pPug->QueryInterface( IIDISupportErrorInfo, (void**)&psei);
if (SUCCEEDED(hr2))
{
// check if object supports СОМ exceptions via IPug methods
// проверяем, поддерживает ли объект исключения СОМ через методы
IPug hr2 = psei->InterfaceSupportsErrorInfo(IIDIPug);
if (hr2 == SOK)
{
// read exception object for this logical thread
// читаем объект исключений для этого логического потока
IErrorInfo *реi = 0;
hr2 = GetErrorInfo(0, &pei);
if (hr2 == SOK)
{
// scrape out source and description strings
// извлекаем строки кода и описания
BSTR bstrSource = 0, bstrDesc = 0;
hr2 = pei->GetDescription(&bstrDesc);
assert(SUCCEEDED(hr2));
hr2 = pei->GetSource(&bstrSource);
assert(SUCCEEDED(hr2));
// display error information to end-user
// показываем информацию об ошибке конечному пользователю
MessageBoxW(0, bstrDesc ? bstrDesc : L"«, bstrSource ? bstrSource : L»", MBOK);
// free resources
// высвобождаем ресурсы
SysFreeString(bstrSource);
SysFreeString(bstrDesc);
pei->Release();
}
}
psei->Release();
}
}
if (hr2!= SOK)
// something went wrong with exception
// что-то неладно с исключением
MessageBox(0, «Snore Failed», «IPug», MBOK);
}
Довольно просто отобразить исключения СОМ в исключения C++, причем в любом месте. Определим следующий класс, который упаковывает объект исключений СОМ и HRESULT в один класс C++:
struct COMException
{
HRESULT mhresult;
// hresult to return
// hresult для возврата IErrorInfo *mpei;
// exception to throw
// исключение для выбрасывания
COMException(HRESULT hresult, REFIID riid, const OLECHAR *pszSource, const OLECHAR *pszDesc, const OLECHAR *pszHelpFile = 0, DWORD dwHelpContext = 0)
{
// create and init an error info object
// создаем и инициализируем объект информации об ошибке
ICreateErrorInfo *рсеi = 0;
HRESULT hr = CreateErrorInfo(&pcei);
assert(SUCCEEDED(hr));
hr = pcei->SetGUID(riid);
assert(SUCCEEDED(hr));
if (pszSource) hr=pcei->SetSource(constcast<OLECHAR*>(pszSource));
assert(SUCCEEDED(hr));
if (pszDesc) hr=pcei->SetDescription(constcast<OLECHAR*>(pszDesc));
assert(SUCCEEDED(hr));
if (pszHelpFile) hr=pcei->SetHelpFile(constcast<OLECHAR*>(pszHelpFile));
assert(SUCCEEDED(hr));
hr = pcei->SetHelpContext(dwHelpContext);
assert(SUCCEEDED(hr));
// hold the HRESULT and IErrorInfo ptr as data members
// сохраняем HRESULT и указатель IErrorInfo как элементы данных
mhresult = hresult;
hr=pcei->QueryInterface(IIDIErrorInfo, (void**)&mpei);
assert(SUCCEEDED(hr));
pcei->Release();
}
};
С использованием только что приведенного С++-класса COMException показанный выше метод Snore может быть модифицирован так, чтобы он преобразовывал любые исключения C++ в исключения СОМ:
STDMETHODIMP PugCat::Snore(void)
{
HRESULT hrex = SOK;
try
{
if (this->IsAsleep()) return this->DoSnore();
else throw COMException(PUGEPUGNOTASLEEP, IIDIPug, OLESTR(«PugCat»), OLESTR(«I am not asleep!»));
}
catch (COMException& ce)
{
// a C++ COMException was thrown
// было сброшено исключение COMException C++
HRESULT hr = SetErrorInfo(0, ce.mpei);
assert(SUCCEEDED(hr));
ce.mpei->Release();
hrex = ce.mhresult;
}
catch (…)
{
// some unidentified C++ exception was thrown
// было выброшено какое-то неидентифицированное исключение C++
COMException ex(EFAIL, IIDIPug, OLESTR(«PugCat»), OLESTR(«A C++ exception was thrown»));
// throw an exception
// возбуждаем исключения
HRESULT SetErrorInfo([in] ULONG reserved, //
m.b.z. [in] IErrorlnfo *pei);
// catch an exception
// перехватываем исключение
HRESULT GetErrorInfo([in] ULONG reserved, // m.b.z.
[out] IErrorInfo **ppei);
Процедура SetErrorInfo вызывается из реализации метода, чтобы связать объект исключения с текущим логическим потоком (logical thread)[1]. GetErrorInfo выбирает объект исключения из текущего логического потока и сбрасывает исключение, так что следующие вызовы GetErrorInfo возвратят SFALSE, показывая тем самым, что необработанных исключений нет. Как следует из приведенных ниже подпрограмм, объекты исключений должны поддерживать по крайней мере интерфейс IErrorInfo:
[ object, uuid(1CF2B120-547D-101B-8E65-08002B2BD119) ]
interface IErrorInfo: IUnknown
{
// get IID of interface that threw exception
// получаем IID того интерфейса, который возбудил исключение
HRESULT GetGUID([out] GUID * pGUID);
// get class name of object that threw exception
// получаем имя класса того объекта, который возбудил исключение
HRESULT GetSource([out] BSTR * pBstrSource);
// get human-readable description of exception
// получаем читабельное описание исключения
HRESULT GetDescription([out] BSTR * pBstrDescription);
// get WinHelp filename of documentation of error
// получаем имя файла WinHelp, содержащего документацию об ошибке
HRESULT GetHelpFile([out] BSTR * pBstrHelpFile);
// get WinHelp context ID for documentation of error
// получаем контекстный идентификатор WinHelp для документации ошибки
HRESULT GetHelpContext([out] DWORD * pdwHelpContext);
}
Специальные объекты исключений могут выбрать другие специфические для исключений интерфейсы в дополнение к IErrorInfo.
СОМ предусматривает по умолчанию реализацию IErrorInfo, которую можно создать с использованием API-функции СОМ CreateErrorInfo:
HRESULT CreateErrorInfo([out] ICreateErrorInfo **ppcei);
В дополнение к IErrorInfo объекты исключений по умолчанию открывают интерфейс ICreateErrorInfo, чтобы позволить пользователю инициализировать состояние нового исключения:
[ object, uuid(22F03340-547D-101B-8E65-08002B2BD119) ]
interface ICreateErrorInfo: IUnknown
{
// set IID of interface that threw exception
// устанавливаем IID интерфейс, который возбудил исключение
HRESULT SetGUID([in] REFGUID rGUID);
// set class name of object that threw exception
// устанавливаем классовое имя объекта, который возбудил исключение
HRESULT SetSource([in, string] OLECHAR* pwszSource);
// set human-readable description of exception
// устанавливаем читабельное описание исключения
HRESULT SetDescription([in, string] OLECHAR* pwszDesc);
// set WinHelp filename of documentation of error
// устанавливаем имя файла WinHelp, содержащего документацию об ошибке
HRESULT SetHelpFile([in, string] OLECHAR* pwszHelpFile);
// set WinHelp context ID for documentation of error
// устанавливаем идентификатор контекста WinHelp для документации ошибки
HRESULT SetHelpContext([in] DWORD dwHelpContext);
}
Заметим, что этот интерфейс просто позволяет пользователю заполнить объект исключения пятью основными атрибутами, доступными из интерфейса IErrorInfo.
Следующая реализация метода выбрасывает СОМ-исключение своему вызывающему объекту, используя объект исключений по умолчанию:
STDMETHODIMP PugCat::Snore(void)
{
if (this->IsAsleep())
// ok to perform operation?
// можно ли выполнять операцию?
return this->DoSnore();
//do operation and return
// выполняем операцию и возвращаемся
//otherwise create an exception object
// в противном случае создаем объект исключений
ICreateErrorInfo *рсеi = 0; HRESULT hr = CreateErrorInfo(&pcei);
assert(SUCCEEDED(hr));
// initialize the exception object
// инициализируем объект исключений
hr = pcei->SetGUID(IIDIPug);
assert(SUCCEEDED(hr));
hr = pcei->SetSource(OLESTR(«PugCat»));
assert(SUCCEEDED(hr));
hr = pcei->SetDescription(OLESTR("I am not asleep!"));
assert(SUCCEEDED(hr));
hr = pcei->SetHelpFile(OLESTR(«C:\\PugCat.hlp»));
assert(SUCCEEDED(hr));
hr = pcei->SetHelpContext(5221);
assert(SUCCEEDED(hr));
// «throw» exception
// «выбрасываем» исключение
IErrorInfo *pei = 0;
hr = pcei->QueryInterface(IIDIErrorInfo, (void**)&pei);
assert(SUCCEEDED(hr));
hr = SetErrorInfo(0, pei);
// release resources and return a SEVERITYERROR result
// высвобождаем ресурсы и возвращаем результат
// SEVERITYERROR (серьезность ошибки)
pei->Release();
pcei->Release();
return PUGEPUGNOTASLEEP;
}
Отметим, что поскольку объект исключений передается в процедуру SetErrorInfo, СОМ сохраняет ссылку на исключение до тех пор, пока оно не будет «перехвачено» вызывающим объектом, использующим GetErrorInfo.
Объекты, которые сбрасывают исключения СОМ, должны использовать интерфейс ISupportErrorInfo , чтобы показывать, какие интерфейсы поддерживают исключения. Этот интерфейс используется клиентами, чтобы установить, верный ли результат дает GetErrorInfo[2]. Этот интерфейс предельно прост:
[ object, uuid(DFOB3060-548F-101B-8E65-08002B2BD119) ]
interface ISupportErrorInfo: IUnknown
{
HRESULT InterfaceSupportsErrorInfo([in] REFIID riid);
}
Предположим, что класс PugCat, рассмотренный в этой главе, сбрасывает исключения из каждого поддерживаемого им интерфейса. Тогда его реализация будет выглядеть так:
STDMETHODIMP PugCat::InterfaceSupportsErrorInfo(REFIID riid)
{
if (riid == IIDIAnimal || riid == IIDICat || riid == IIDIDog || riid == IIDIPug) return SOK;
else return SFALSE;
}
Ниже приведен пример клиента, который надежно обрабатывает исключения, используя ISupportErrorInfo и GetErrorInfo:
void TellPugToSnore(/*[in]*/ IPug *pPug)
{
// call a method
// вызываем метод
HRESULT hr = pPug->Snore();
if (FAILED(hr))
{
// check to see if object supports СОМ exceptions
// проверяем, поддерживает ли объект исключения СОМ
ISupportErrorInfo *psei = 0;
HRESULT hr2 =pPug->QueryInterface( IIDISupportErrorInfo, (void**)&psei);
if (SUCCEEDED(hr2))
{
// check if object supports СОМ exceptions via IPug methods
// проверяем, поддерживает ли объект исключения СОМ через методы
IPug hr2 = psei->InterfaceSupportsErrorInfo(IIDIPug);
if (hr2 == SOK)
{
// read exception object for this logical thread
// читаем объект исключений для этого логического потока
IErrorInfo *реi = 0;
hr2 = GetErrorInfo(0, &pei);
if (hr2 == SOK)
{
// scrape out source and description strings
// извлекаем строки кода и описания
BSTR bstrSource = 0, bstrDesc = 0;
hr2 = pei->GetDescription(&bstrDesc);
assert(SUCCEEDED(hr2));
hr2 = pei->GetSource(&bstrSource);
assert(SUCCEEDED(hr2));
// display error information to end-user
// показываем информацию об ошибке конечному пользователю
MessageBoxW(0, bstrDesc ? bstrDesc : L"«, bstrSource ? bstrSource : L»", MBOK);
// free resources
// высвобождаем ресурсы
SysFreeString(bstrSource);
SysFreeString(bstrDesc);
pei->Release();
}
}
psei->Release();
}
}
if (hr2!= SOK)
// something went wrong with exception
// что-то неладно с исключением
MessageBox(0, «Snore Failed», «IPug», MBOK);
}
Довольно просто отобразить исключения СОМ в исключения C++, причем в любом месте. Определим следующий класс, который упаковывает объект исключений СОМ и HRESULT в один класс C++:
struct COMException
{
HRESULT mhresult;
// hresult to return
// hresult для возврата IErrorInfo *mpei;
// exception to throw
// исключение для выбрасывания
COMException(HRESULT hresult, REFIID riid, const OLECHAR *pszSource, const OLECHAR *pszDesc, const OLECHAR *pszHelpFile = 0, DWORD dwHelpContext = 0)
{
// create and init an error info object
// создаем и инициализируем объект информации об ошибке
ICreateErrorInfo *рсеi = 0;
HRESULT hr = CreateErrorInfo(&pcei);
assert(SUCCEEDED(hr));
hr = pcei->SetGUID(riid);
assert(SUCCEEDED(hr));
if (pszSource) hr=pcei->SetSource(constcast<OLECHAR*>(pszSource));
assert(SUCCEEDED(hr));
if (pszDesc) hr=pcei->SetDescription(constcast<OLECHAR*>(pszDesc));
assert(SUCCEEDED(hr));
if (pszHelpFile) hr=pcei->SetHelpFile(constcast<OLECHAR*>(pszHelpFile));
assert(SUCCEEDED(hr));
hr = pcei->SetHelpContext(dwHelpContext);
assert(SUCCEEDED(hr));
// hold the HRESULT and IErrorInfo ptr as data members
// сохраняем HRESULT и указатель IErrorInfo как элементы данных
mhresult = hresult;
hr=pcei->QueryInterface(IIDIErrorInfo, (void**)&mpei);
assert(SUCCEEDED(hr));
pcei->Release();
}
};
С использованием только что приведенного С++-класса COMException показанный выше метод Snore может быть модифицирован так, чтобы он преобразовывал любые исключения C++ в исключения СОМ:
STDMETHODIMP PugCat::Snore(void)
{
HRESULT hrex = SOK;
try
{
if (this->IsAsleep()) return this->DoSnore();
else throw COMException(PUGEPUGNOTASLEEP, IIDIPug, OLESTR(«PugCat»), OLESTR(«I am not asleep!»));
}
catch (COMException& ce)
{
// a C++ COMException was thrown
// было сброшено исключение COMException C++
HRESULT hr = SetErrorInfo(0, ce.mpei);
assert(SUCCEEDED(hr));
ce.mpei->Release();
hrex = ce.mhresult;
}
catch (…)
{
// some unidentified C++ exception was thrown
// было выброшено какое-то неидентифицированное исключение C++
COMException ex(EFAIL, IIDIPug, OLESTR(«PugCat»), OLESTR(«A C++ exception was thrown»));