HRESULT - HRESULT

В области компьютерное программирование, то HRESULT это тип данных использовался в операционных системах Windows и более ранних версиях операционной системы IBM / Microsoft OS / 2 для представления состояний ошибок и предупреждений.

Первоначальная цель HRESULT состояла в том, чтобы формально определить диапазоны кодов ошибок как для общего, так и для внутреннего использования Microsoft, чтобы предотвратить конфликты между кодами ошибок в различных подсистемах операционной системы OS / 2.

HRESULT - это числовые коды ошибок. Различные биты в HRESULT кодируют информацию о природе кода ошибки и его происхождении.

Коды ошибок HRESULT чаще всего встречаются в COM программирование, где они образуют основу для стандартизированного соглашения об обработке ошибок COM.

Формат HRESULT

Значение HRESULT имеет 32 бита, разделенных на три поля: строгость код, а средство код и ошибка код. Код серьезности указывает, представляет ли возвращаемое значение информацию, предупреждение или ошибку. Код объекта определяет область системы, в которой возникла ошибка. Код ошибки - это уникальный номер, который присваивается для представления исключения. Каждому исключению сопоставляется отдельный HRESULT.

Объект - это либо название объекта, либо другой отличительный идентификатор; Серьезность - это одна буква S или E, которая указывает, был ли вызов функции успешным (S) или возникла ошибка (E); Причина - это идентификатор, описывающий значение кода. Например, код состояния STG_E_FILENOTFOUND указывает, что произошла ошибка, связанная с хранением; в частности, запрошенный файл не существует. Следует иметь в виду, что значение HRESULT вполне может отображаться как беззнаковое шестнадцатеричное значение. [1]

HRESULT организованы следующим образом:[2]

Кусочек313029282726252423222120191817161514131211109876543210
ПолеSрCNИксСредствоКод

Детали формата

  • S - серьезность - указывает успех / неудачу
    • 0 - Успех
    • 1 - Отказ
  • R - Зарезервированная часть кода объекта соответствует второму биту серьезности NT.
    • 1 - Серьезный отказ
  • C - Клиент. Этот бит указывает, определено ли значение пользователем или Microsoft.
    • 0 - определено Microsoft
    • 1 - определяется заказчиком
  • N - Зарезервированная часть кода объекта. Используется для обозначения отображенного значения состояния NT.
  • X - Зарезервированная часть кода объекта. Зарезервировано для внутреннего использования. Используется для обозначения значений HRESULT, которые не являются значениями статуса, а вместо этого являются идентификаторами сообщений для отображаемых строк.
  • Facility - указывает системную службу, виновную в ошибке. Примеры кодов объектов показаны ниже (полный список см. [2]).
    • 1 - RPC
    • 2 - Отправка (COM-рассылка)
    • 3 - Хранилище (хранилище OLE)
    • 4 - ITF (управление интерфейсом COM / OLE)
    • 7 - Win32 (необработанные коды ошибок Win32)
    • 8 - Окна
    • 9 - SSPI
    • 10 - Контроль
    • 11 - CERT (сертификат клиента или сервера)
    • ...
  • Код - это код статуса объекта.

Код объекта ITF впоследствии был переработан как диапазон, в котором компоненты COM могут определять свой собственный код ошибки для конкретного компонента.

Как работают HRESULT

HRESULT - это непрозрачный дескриптор результата, который определяется как нулевое или положительное значение для успешного возврата из функции и отрицательное значение для отказа. Как правило, успешные функции возвращают S_OK Значение HRESULT (равное нулю). Но в редких случаях функции могут возвращать коды успеха с дополнительной информацией, например S_FALSE = 0x01.

Когда отображаются значения HRESULT, они часто отображаются как беззнаковый шестнадцатеричный значение, обычно обозначаемое 0x префикс. В этом случае число, указывающее на сбой, можно определить, начав с шестнадцатеричной цифры 8 или выше.

Изначально значения HRESULT были определены в операционной системе IBM / Microsoft OS / 2 как код возврата ошибки общего назначения и впоследствии приняты в Windows NT. Microsoft Visual Basic значительно улучшил механизмы отчетов об ошибках HRESULT, добавив IErrorInfo объект с кодом ошибки HRESULT, сохраняя указатель на COM-объект IErrorInfo в локальном хранилище потока. Механизм IErrorInfo позволяет программам связывать широкий спектр информации с конкретной ошибкой HRESULT: класс объекта, вызвавшего ошибку, интерфейс объекта, вызвавшего ошибку, текст ошибки; и ссылку на раздел справки в файле справки. Кроме того, получатели ошибки HRESULT могут по запросу получить локализованный текст сообщения об ошибке.

Впоследствии HRESULT и связанный IErrorInfo Механизм использовался как механизм сообщения об ошибках по умолчанию в COM.

Поддержка механизма IErrorInfo в Windows очень непоследовательна. Старые API Windows, как правило, не поддерживают его вообще, возвращая HRESULT без каких-либо IErrorInfo данные. Более современные подсистемы Windows COM часто предоставляют обширную информацию об ошибках в описании сообщения объекта IErrorInfo. Более продвинутые функции механизмов ошибок IErrorInfo - справочные ссылки и локализация по запросу - используются редко.

в .NET Framework, Коды ошибок HRESULT / IErrorInfo переводятся в CLR исключения при переходе от нативного к управляемому коду; и исключения CLR преобразуются в коды ошибок HRESULT / IErrorInfo при переходе от управляемого к собственному COM код.

Использование HRESULT

В winerror.h файл определяет некоторые общие значения HRESULT. Жестко закодированные значения HRESULT иногда кодируются в связанных файлах заголовков (файлах .h) для данной подсистемы. Эти значения также определены в соответствующих файлах заголовков (.h) с платформами Microsoft Windows. SDK или DDK.

Чтобы проверить успешность вызова, возвращающего HRESULT, убедитесь, что S поле равно 0 (т.е.число неотрицательно) или используйте макрос FAILED (). Чтобы получить Код часть HRESULT, используйте макрос HRESULT_CODE (). Вы также можете использовать инструмент под названием ERR.EXE чтобы взять значение и преобразовать его в соответствующую строку ошибки. Другой инструмент под названием ERRLOOK.EXE также может использоваться для отображения строк ошибок, связанных с заданным значением HRESULT. ERRLOOK.EXE можно запустить из Visual Studio командная строка.

Родной Windows SetErrorInfo и GetErrorInfo API используются для связывания кодов возврата HRESULT с соответствующим IErrorInfo объект.

В FormatMessage Функцию API можно использовать для преобразования некоторых значений HRESULT, не относящихся к IErrorInfo, в читаемую пользователем строку.

Примеры

  • 0x80070005
    • 0x8 - Отказ
    • 0x7 - Win32
    • 0x5 - «E_FAULT»
  • 0x80090032
    • 0x8 - Отказ
    • 0x9 - ГГПИ
    • 0x32 - «Запрос не поддерживается»[3]

Рекомендации

  1. ^ «Структура кодов ошибок COM».
  2. ^ а б Справочник по коду ошибки Windows MSDN. Ссылка перепроверена 24 сентября 2014 г.
  3. ^ [1] Коды ошибок Win32

внешняя ссылка