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.

Facility is either the facility name or some other distinguishing identifier; Severity is a single letter, S or E, that indicates whether the function call succeeded (S) or produced an error (E); and Reason is an identifier that describes the meaning of the code. For example, the status code STG_E_FILENOTFOUND indicates a storage-related error has occurred; specifically, a requested file does not exist. One should keep in mind that an HRESULT value may well be displayed as an unsigned hexadecimal value. [1]

HRESULTs are organized as follows:[2]

Bit 313029282726252423222120191817161514131211109876543210
Field SRCNXFacilityCode

Format details
  • S - Severity - indicates success/fail
    • 0 - Success
    • 1 - Failure
  • R - Reserved portion of the facility code, corresponds to NT's second severity bit.
    • 1 - Severe Failure
  • C - Customer. This bit specifies if the value is customer-defined or Microsoft-defined.
    • 0 - Microsoft-defined
    • 1 - Customer-defined
  • N - Reserved portion of the facility code. Used to indicate a mapped NT status value.
  • X - Reserved portion of the facility code. Reserved for internal use. Used to indicate HRESULT values that are not status values, but are instead message ids for display strings.
  • Facility - indicates the system service that is responsible for the error. Example facility codes are shown below (for the full list see [2]).
    • 1 - RPC
    • 2 - Dispatch (COM dispatch)
    • 3 - Storage (OLE storage)
    • 4 - ITF (COM/OLE Interface management)
    • 7 - Win32 (raw Win32 error codes)
    • 8 - Windows
    • 9 - SSPI
    • 10 - Control
    • 11 - CERT (Client or server certificate)
    • ...
  • Code - is the facility's status code

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
  • 0x80070005
    • 0x8 - Failure
    • 0x7 - Win32
    • 0x5 - "E_FAULT"
  • 0x80090032
    • 0x8 - Failure
    • 0x9 - SSPI
    • 0x32 - "The request is not supported"[3]

References
  1. "Structure of COM Error Codes".
  2. MSDN Windows Error Code reference. Reference re-verified September 24, 2014
  3. 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.