ЧРЕЗУЛЬТАТ

HRESULT — это компьютерного программирования тип данных который представляет состояние завершения функции , .

Он используется в исходном коде приложений, предназначенных для Microsoft Windows и более ранних IBM/Microsoft OS/2 операционных систем , но его конструкция не ограничивает его использование этими средами; его можно использовать в любой системе, поддерживающей 32-битные целые числа .

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

HRESULT спроектирован так, чтобы одновременно представлять собой простое числовое значение и структуру полей, указывающих серьезность, объект и код состояния.

Использование HRESULT чаще всего встречается в программировании COM , где оно формирует основу для стандартизированного механизма обработки ошибок , но его использование не ограничивается COM. Например, его можно использовать в качестве альтернативы более традиционному использованию логического результата «пройден/не пройден».

Структура данных

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

Серьезность: указывает, была ли функция успешной или неудачной.
Объект: определяет часть системы, к которой применяется статус.
Код: определяет конкретное состояние в контексте объекта.

Значение HRESULT представляет собой структуру со следующими битовыми полями : ^[2]

Кусочек	31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
Поле	С	Р	С	Н	Х	Средство											Код

S — серьезность — указывает на успех (0) или неудачу (1).
Р – Зарезервировано; соответствует второму биту серьезности NTSTATUS (1 — серьезный сбой)
С – Клиент. Указывает, является ли значение определенным Microsoft (0) или клиентом (1).
Н – Зарезервировано; используется для указания значения NTSTATUS, которое было сопоставлено с HRESULT.
X — зарезервировано для внутреннего использования; используется для обозначения значения, которое не является статусом, а является идентификатором сообщения для отображаемых строк
Facility – указывает системную службу, отвечающую за состояние; примеры:
- 1 - ПКП
- 2 - Диспетчеризация (COM-диспетчерская)
- 3 — Хранилище (OLE-хранилище)
- 4 — ITF (управление интерфейсом COM/OLE)
- 7 — Win32 (необработанные коды ошибок Win32)
- 8 - Окна
- 9 - ССПИ
- 10 - Управление
- 11 — CERT (сертификат клиента или сервера)
- ...
Код - код состояния объекта

Числовое представление

Значение HRESULT иногда отображается как шестнадцатеричное значение из 8 цифр.

Примеры: ^[3]

0x80070005
- 0x8 - Статус: Сбой
- 0x7 - Средство: Win32
- 0x5 - Код: E_FAULT
0x80090032
- 0x8 - Статус: Сбой
- 0x9 - Объект: ССПИ
- 0x32 - Код: Запрос не поддерживается.

Иногда значение HRESULT отображается как целое число со знаком, но это встречается реже и его труднее читать.

Представление имени

HRESULT иногда представляется как идентификатор в формате Facility_Severity_Reason : ^[4]

Объект — это либо название объекта, либо какой-либо другой отличительный идентификатор.
Серьезность — одна буква: S — успешно, E — ошибка (неудачно).
Причина описывает смысл кода

Например, STG_E_FILENOTFOUND указывает на ошибку, связанную с хранилищем: файл не существует.

Часть объекта опускается, если объект равен 0 (FACILITY_NULL) или для некоторых очень распространенных значений. Например: S_OK, E_FAIL, E_INVALIDARG.

Это представление легче читать, чем числовой формат, но оно менее точное, поскольку, хотя и основано на соглашении, не существует определенного алгоритма преобразования между значением и именем.

Иерроринфо

HRESULT изначально был определен в операционной системе IBM/Microsoft OS/2 как код возврата ошибки общего назначения и впоследствии принят в Windows NT.

Microsoft Visual Basic существенно усовершенствовал механизмы отчетов об ошибках HRESULT, связав объект IErrorInfo с HRESULT и сохранив (указатель на) объект 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

Поскольку HRESULT определяется как целое число со знаком, а поле серьезности является старшим битом, отрицательное значение указывает на сбой, а другие значения указывают на успех. Наиболее часто используемый код успеха: S_OK который имеет значение 0. Однако в редких случаях функция возвращает код успеха с дополнительной информацией, такой как S_FALSE который имеет значение 1.

Когда значение HRESULT отображается в шестнадцатеричном виде (обычно для целей отладки), разработчик может идентифицировать значение как указывающее на сбой, если оно начинается с цифры 8 или больше в восьмом и наиболее значимом месте. Обратите внимание: если значение не дополнено 8 цифрами с ведущими нулями, значение может быть ошибочно воспринято как неудачное. Например, 80005 — это успех, даже если оно начинается с 8. Если дополнить его 8 цифрами, это становится ясным: 00080005. Это несколько надуманно, поскольку обычно успех равен 0, что явно является кодом успеха.

Программные способы проверки состояния сбоя — это проверка на отрицательный результат или использование определяемого системой макроса. ^[5]

HRESULT hr = func(...);
if (hr < 0) ; // failed
if (hr >= 0) ; // succeeded
if (FAILED(hr)) ; // failed
if (SUCCEEDED(hr)) ; // succeeded

Тестирование на 0, например (hr) или (!hr) будет работать большую часть времени, но неверно для редко используемых кодов успеха, кроме S_OK такой как S_FALSE.

Чтобы получить часть кода HRESULT, используйте HRESULT_CODE() макрос.

Используйте инструмент ERR.EXE для преобразования значения в соответствующий текст сообщения.

Инструмент ERRLOOK.EXE можно использовать для отображения строк ошибок, связанных с данным значением HRESULT. Его можно запустить из командной строки Visual Studio .

Win32 SetErrorInfo связывает значение HRESULT с соответствующим IErrorInfo объект. GetErrorInfo читает эту информацию.

Win32 FormatMessage можно использовать для получения удобочитаемого описания некоторых значений HRESULT, отличных от IErrorInfo.

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

Происхождение имени

Имя HRESULT означает «дескриптор результата», поскольку многие другие типы Windows используют H для обозначения дескриптора. Например, HMODULE — это дескриптор модуля, что означает, что значение HMODULE относится к ресурсу модуля. Однако значение HRESULT не ссылается на ресурс, поэтому оно не является дескриптором. По словам Рэймонда Чена, «раньше это действительно был дескриптор объекта, который содержал обширную информацию об ошибках... Команда COM решила, что соотношение цена/выгода просто не стоит того, поэтому HRESULT превратился в простое число. Но название прижилось». ^[6]

Ссылки

^ Куинн Радич. «Типы данных Windows (BaseTsd.h) — приложения Win32» . docs.microsoft.com . Проверено 10 июля 2022 г.
^ «[MS-ERREF]: HRESULT» . docs.microsoft.com . Проверено 10 июля 2022 г.
^ «[MS-ERREF]: коды ошибок Win32» . docs.microsoft.com . Проверено 10 июля 2022 г.
^ Стивихимс. «Структура кодов ошибок COM — приложения Win32» . docs.microsoft.com . Проверено 11 июля 2022 г.
^ Стивихимс. «Использование макросов для обработки ошибок — приложения Win32» . docs.microsoft.com . Проверено 10 июля 2022 г.
^ Чен, Рэймонд (17 января 2018 г.). «Почему HRESULT начинается с H, если он ни на что не указывает?» . Старая новая вещь . Проверено 11 июля 2022 г.

[1] Куинн Радич. «Типы данных Windows (BaseTsd.h) — приложения Win32» . docs.microsoft.com . Проверено 10 июля 2022 г.

[2] «[MS-ERREF]: HRESULT» . docs.microsoft.com . Проверено 10 июля 2022 г.

[3] «[MS-ERREF]: коды ошибок Win32» . docs.microsoft.com . Проверено 10 июля 2022 г.

[4] Стивихимс. «Структура кодов ошибок COM — приложения Win32» . docs.microsoft.com . Проверено 11 июля 2022 г.

[5] Стивихимс. «Использование макросов для обработки ошибок — приложения Win32» . docs.microsoft.com . Проверено 10 июля 2022 г.

[6] Чен, Рэймонд (17 января 2018 г.). «Почему HRESULT начинается с H, если он ни на что не указывает?» . Старая новая вещь . Проверено 11 июля 2022 г.

[1]

[2]

[3]

[4]

[5]

[6]