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 or produced an error ; 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 unsignedhexadecimal value. HRESULTs are organized as follows:
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.
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. 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 messageon 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 for a given subsystem. These values are also defined in the corresponding header 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 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 to take the value and translate it to the corresponding error string. Another tool called can also be used to display error strings associated with a given HRESULT value. ERRLOOK.EXE can be run from within a Visual Studiocommand prompt. The Windows native SetErrorInfo and GetErrorInfo APIs are used to associate HRESULT return codes with a corresponding IErrorInfo object. The API function can be used to convert some non-IErrorInfo HRESULTs into a user-readable string.
