User:Chchwy/HRESULT
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.
| Bit | 3 1 |
3 0 |
2 9 |
2 8 |
2 7 |
2 6 |
2 5 |
2 4 |
2 3 |
2 2 |
2 1 |
2 0 |
1 9 |
1 8 |
1 7 |
1 6 |
1 5 |
1 4 |
1 3 |
1 2 |
1 1 |
1 0 |
9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Field | S | R | C | N | X | Facility | Code | |||||||||||||||||||||||||
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.
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.
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 mechanims—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- 8 - Failure
- 7 - Win32
- 5 - "Access Denied"
0x80090032- 8 - Failure
- 9 - SSPI
- 32 - "The request is not supported"