Инна Аринович
Антон Григорьев
дата публикации 25-01-2005 06:14

---

Версия для печати

Тип HRESULT является одним из средств контроля ошибок в COM/DCOM. Этот тип представляет собой 32-битное число, в котором кодируется результат операции. Старший бит этого числа равен 1, если была ошибка, и 0, если всё прошло нормально. Следующие 4 бита зарезервированы для дальнейшего использования. Следующие 11 бит показывают, где возникла ошибка (это значение обычно называется facility code, что можно приблизительно перевести как код устройства, если подразумевать под устройством не только аппаратные, но и логические устройства). Младшие 16 бит кодируют собственно ошибку.

Для расшифровки значения типа HRESULT можно использовать утилиту ErrLook.exe из пакета Visual Studio. Более удобным средством расшифровки является утилита Decode, входящая в состав MSDN и доступная для скачивания по адресу http://support.microsoft.com/default.aspx?scid=kb;en-us;122957 (к сожалению, адреса конкретных страниц в MSDN иногда меняются, поэтому, возможно, через некоторое время после выхода этой статьи ссылка потеряет актуальность - в этом случае рекомендуем воспользоваться поиском по словам HRESULT и decoding). Утилита Decode включена в MSDN как пример в исходных кодах на C++, поэтому, не имея компилятора для этого языка, воспользоваться данной утилитой не удастся. В некоторых случаях удаётся понять смысл результата, воспользовавшись поиском по исходным файлам стандартных модулей в Delphi. Например, если функция вернула результат с кодом $80004002, то поиск строки "$80004002" в этих файлах покажет, что такое значение имеет константа E_NOINTERFACE, объявленная в модуле System. Смысл этой константы затем можно выяснить, задав поиск строки "E_NOINTERFACE" в MSDN.

В модели COM рекомендуется, чтобы функции, экспортируемые сервером и клиентом, возвращали результат типа HRESULT, по которому можно судить об успешном или неуспешном выполнении функции. Даже если логика работы функции подразумевает возвращение какого-то результата, его рекомендуется возвращать через параметры, передаваемые по ссылке, а тип самой функции должен быть HRESULT. В модели DCOM использование HRESULT - это уже не рекомендация, а обязательное требование. Некоторые функции стандартных интерфейсов, доставшиеся DCOM в наследство от COM (например, функции AddRef и Release интерфейса IUnknown), тем не менее, имеют тип, отличный от HRESULT. Но это допускается только для стандартных интерфейсов в целях совместимости, а все функции новых серверов должны иметь тип HRESULT.

В Windows.pas определены функции Succeeded и Failed, принимающие в качестве параметра HRESULT и возвращающие результат типа Boolean. Смысл функций очевиден из их названий: Succeeded возвращает True, если переданное ей значение кодирует успех, Failed - если значение кодирует ошибку. Подключив модуль ComObj.pas, можно использовать процедуру OleCheck, которая принимает в качестве параметра выражение типа HRESULT и создаёт исключительную ситуацию EOleSysError, если значение этого выражения кодирует ошибку. В качестве параметра функции OleCheck удобно передавать выражение, возвращаемое функциями, имеющими тип HRESULT: в случае ошибки возникнет исключение, которое легко обработать в блоке try/except.

Существуют предопределённые константы типа HRESULT, часть которых показана в таблице. Значения констант могут быть разными на разных платформах, поэтому в целях совместимости лучше пользоваться их символьными именами, а не значениями.

В таблице приведены в качестве примера некоторые константы типа HRESULT. В дальнейшем по мере необходимости мы будем знакомиться с другими константами. Кроме того, разработчик DCOM-сервера может вводить свои константы для обозначения ошибок, специфичных для данного сервера. При наименовании констант Microsoft рекомендует начинать их с "S_" (или вставлять в середину "_S_"), если подразумевается успешное завершение операции и начинать константу с "E_" (или вставлять в середину "_E_"), если кодируется ошибка.