HRESULT: Тип данных для кодов возврата функций в Windows и COM

Computer programming data type

HRESULT is a computer programming data type that represents the completion status of a function. It is used in the source code of applications targeting Microsoft Windows and earlier IBM/Microsoft OS/2 operating systems, but its design does not limit its use to these environments; it can be used in any system supporting 32 bit integers. The original purpose of HRESULT was to lay out ranges of status codes for both public and Microsoft internal use in order to prevent collisions between status codes in different subsystems of the OS/2 operating system. An HRESULT is designed to simultaneously be both a simple numerical value and a structure of fields indicating severity, facility and status code. Use of HRESULT is most commonly encountered in COM programming, where it forms the basis for a standardized error handling mechanism, but its use is not limited to COM. For example, it can be used as an alternative to the more traditional use of a boolean pass/fail result.

The HRESULT was originally defined in the IBM/Microsoft OS/2 operating system as a general purpose error return code, and subsequently adopted in Windows NT. Microsoft Visual Basic substantially enhanced the HRESULT error reporting mechanisms, by associating an IErrorInfo object with an HRESULT and storing (a pointer to) an IErrorInfo object in thread local storage. The IErrorInfo mechanism allows programs to associate a broad variety of information with a particular HRESULT error: the class of the object that raised the error, the interface of the object that raised the error, error text; and a link to a help topic in a help file. In addition, receivers of an HRESULT error can obtain localized text for the error message on demand. Subsequently, HRESULT, and the associated IErrorInfo mechanism were used as the default error reporting mechanism in COM. Support of the IErrorInfo mechanism in Windows is highly inconsistent. Older Windows APIs tend to not support it at all, returning HRESULTs without any IErrorInfo data. More modern Windows COM subsystems often provide extensive error information in the message description of the IErrorInfo object. The more advanced features of the IErrorInfo error mechanisms—help links, and on demand localization—are rarely used. In the NET Framework, HRESULT/IErrorInfo error codes are translated into CLR exceptions when transitioning from native to managed code; and CLR exceptions are translated to HRESULT/IErrorInfo error codes when transitioning from managed to native COM code.

The name HRESULT appears to mean "result handle" since many other Windows types use H to mean handle. For example, HMODULE is a module handle which means an HMODULE value refers to a module resource. However, an HRESULT value does not refer to a resource so it is not a handle. According to Raymond Chen "in the old days it really was a handle to an object that contained rich error information The COM team decided that the cost/benefit simply wasn’t worth it, so the HRESULT turned into a simple number. But the name stuck."