Исключения
СОМ имеет специфическую поддержку выбрасывания (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). GetErrorInfo выбирает объект исключения из текущего логического потока и сбрасывает исключение, так что следующие вызовы GetErrorInfo возвратят S_FALSE, показывая тем самым, что необработанных исключений нет. Как следует из приведенных ниже подпрограмм, объекты исключений должны поддерживать по крайней мере интерфейс 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(IID_IPug); 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(IID_IErrorInfo, (void**)&pei); assert(SUCCEEDED(hr)); hr = SetErrorInfo(0, pei); // release resources and return a SEVERITY_ERROR result // высвобождаем ресурсы и возвращаем результат // SEVERITY_ERROR (серьезность ошибки) pei->Release(); pcei->Release(); return PUG_E_PUGNOTASLEEP; }
Отметим, что поскольку объект исключений передается в процедуру SetErrorInfo, СОМ сохраняет ссылку на исключение до тех пор, пока оно не будет "перехвачено" вызывающим объектом, использующим GetErrorInfo.
Объекты, которые сбрасывают исключения СОМ, должны использовать интерфейс ISupportErrorInfo, чтобы показывать, какие интерфейсы поддерживают исключения. Этот интерфейс используется клиентами, чтобы установить, верный ли результат дает GetErrorInfo. Этот интерфейс предельно прост:
[ object, uuid(DFOB3060-548F-101B-8E65-08002B2BD119) ] interface ISupportErrorInfo: IUnknown { HRESULT InterfaceSupportsErrorInfo([in] REFIID riid); }
Предположим, что класс PugCat, рассмотренный в этой главе, сбрасывает исключения из каждого поддерживаемого им интерфейса. Тогда его реализация будет выглядеть так:
STDMETHODIMP PugCat::InterfaceSupportsErrorInfo(REFIID riid) { if (riid == IID_IAnimal riid == IID_ICat riid == IID_IDog riid == IID_IPug) return S_OK; else return S_FALSE; }
Ниже приведен пример клиента, который надежно обрабатывает исключения, используя 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( IID_ISupportErrorInfo, (void**)&psei); if (SUCCEEDED(hr2)) { // check if object supports СОМ exceptions via IPug methods // проверяем, поддерживает ли объект исключения СОМ через методы IPug hr2 = psei->InterfaceSupportsErrorInfo(IID_IPug); if (hr2 == S_OK) { // read exception object for this logical thread // читаем объект исключений для этого логического потока IErrorInfo *реi = 0; hr2 = GetErrorInfo(0, &pei); if (hr2 == S_OK) { // 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"", MB_OK); // free resources // высвобождаем ресурсы SysFreeString(bstrSource); SysFreeString(bstrDesc); pei->Release(); } } psei->Release(); } } if (hr2 != S_OK) // something went wrong with exception // что-то неладно с исключением MessageBox(0, "Snore Failed", "IPug", MB_OK); }
Довольно просто отобразить исключения СОМ в исключения C++, причем в любом месте. Определим следующий класс, который упаковывает объект исключений СОМ и HRESULT в один класс C++:
struct COMException { HRESULT m_hresult; // hresult to return // hresult для возврата IErrorInfo *m_pei; // 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(const_cast<OLECHAR*>(pszSource)); assert(SUCCEEDED(hr)); if (pszDesc) hr=pcei->SetDescription(const_cast<OLECHAR*>(pszDesc)); assert(SUCCEEDED(hr)); if (pszHelpFile) hr=pcei->SetHelpFile(const_cast<OLECHAR*>(pszHelpFile)); assert(SUCCEEDED(hr)); hr = pcei->SetHelpContext(dwHelpContext); assert(SUCCEEDED(hr)); // hold the HRESULT and IErrorInfo ptr as data members // сохраняем HRESULT и указатель IErrorInfo как элементы данных m_hresult = hresult; hr=pcei->QueryInterface(IID_IErrorInfo, (void**)&m_pei); assert(SUCCEEDED(hr)); pcei->Release(); } };
С использованием только что приведенного С++-класса COMException показанный выше метод Snore может быть модифицирован так, чтобы он преобразовывал любые исключения C++ в исключения СОМ:
STDMETHODIMP PugCat::Snore(void) { HRESULT hrex = S_OK; try { if (this->IsAsleep()) return this->DoSnore(); else throw COMException(PUG_E_PUGNOTASLEEP, IID_IPug, OLESTR("PugCat"), OLESTR("I am not asleep!")); } catch (COMException& ce) { // a C++ COMException was thrown // было сброшено исключение COMException C++ HRESULT hr = SetErrorInfo(0, ce.m_pei); assert(SUCCEEDED(hr)); ce.m_pei->Release(); hrex = ce.m_hresult; } catch (...) { // some unidentified C++ exception was thrown // было выброшено какое-то неидентифицированное исключение C++ COMException ex(E_FAIL, IID_IPug, OLESTR("PugCat"), OLESTR("A C++ exception was thrown")); HRESULT hr = SetErrorInfo(0, ex.m_pei); assert(SUCCEEDED(hr)); ex.m_pei->Release(); hrex = ex.m_hresult; } return hrex; }
Заметим, что реализация метода заботится о том, чтобы не позволить чисто С++-исключениям переходить через границы метода. Таково безусловное требование СОМ.
1
Спецификация СОМ использует термин логический поток (logical thread) для наименования последовательности вызовов методов, которая может превосходить физический OS-поток.
2
Объект, который обеспечивает выполнение GetErrorInfo, декларирует, что он явно программирует с использованием исключений СОМ и что никаких ошибочных исключений, сброшенных объектами младшего уровня, случайно не распространилось.
