HRESULT

In the field of computer programming, the HRESULT is a data type used in Windows operating systems, and the earlier IBM/Microsoft OS/2 operating system, to represent error conditions, and warning conditions.

The original purpose of HRESULTs was to formally lay out ranges of error codes for both public and Microsoft internal use in order to prevent collisions between error codes in different subsystems of the OS/2 operating system.

HRESULTs are numerical error codes. Various bits within an HRESULT encode information about the nature of the error code, and where it came from.

HRESULT error codes are most commonly encountered in COM programming, where they form the basis for a standardized COM error handling convention.

HRESULT format

An HRESULT value has 32 bits divided into three fields: a severity code, a facility code, and an error code. The severity code indicates whether the return value represents information, warning, or error. The facility code identifies the area of the system responsible for the error. The error code is a unique number that is assigned to represent the exception. Each exception is mapped to a distinct HRESULT.

HRESULTs are organized as follows:[1]

Bit 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
Field S R C N X Facility Code

Format details

The ITF facility code has subsequently been recycled as the range in which COM components can define their own component-specific error code.

How HRESULTs work

An HRESULT is an opaque result handle defined to be zero or positive for a successful return from a function, and negative for a failure. Generally, successful functions return the S_OK HRESULT value (which is equal to zero). But in rare circumstances, functions may return success codes with additional information e.g. S_FALSE=0x01.

When HRESULTs are displayed, they are often rendered as an unsigned hexadecimal value, usually indicated by a 0x prefix. In this case, a number indicating failure can be identified by starting with hexadecimal figure 8 or higher.

HRESULTS were 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 error code, by storing a pointer to an IErrorInfo COM 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 will 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.

Using HRESULTs

The winerror.h file defines some generic HRESULT values. Hard-coded HRESULT values are sometimes encoded in associated header files (.h files) for a given subsystem. These values are also defined in the corresponding header (.h) files with the Microsoft Windows Platforms SDK or DDK.

To check if a call that returns an HRESULT succeeded, make sure the S field is 0 (i.e. the number is non-negative) or use the FAILED() macro. To obtain the Code part of an HRESULT, use the HRESULT_CODE() macro. You can also use a tool called ERR.EXE to take the value and translate it to the corresponding error string. Another tool called ERRLOOK.EXE can also be used to display error strings associated with a given HRESULT value. ERRLOOK.EXE can be run from within a Visual Studio command prompt.

The Windows native SetErrorInfo and GetErrorInfo APIs are used to associate HRESULT return codes with a corresponding IErrorInfo object.

The FormatMessage API function can be used to convert some non-IErrorInfo HRESULTs into a user-readable string.

Examples

References

  1. 1 2 MSDN Windows Error Code reference. Reference re-verified September 24, 2014
  2. ↑ Win32 Error Codes
This article is issued from Wikipedia. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.