HRESULT
≈ 7 min read
Names in other languages
No names in other languages are held for this entry yet.
Article bodies are English and are not machine-translated. A name in another language is not a translation of the article.
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.
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.
Data structure
HRESULT is defined in a system header file as a 32-bit, signed integer and is often treated opaquely as an integer, especially in code that consumes a function that returns HRESULT.
A HRESULT value consists of the following separate items: Severity: indicates whether the function succeeded or failed Facility: identifies the part of the system for which the status applies Code: identifies a particular condition in the context of the facility An HRESULT value is a structure with the following bit-fields: S - Severity; indicates success (0) or failure (1) R - Reserved; corresponds to NTSTATUS's second severity bit (1 - Severe Failure) C - Customer; specifies whether the value is Microsoft-defined (0) or customer-defined (1) N - Reserved; used to indicate an NTSTATUS value that has been mapped to a HRESULT X - Reserved for internal use; used to indicate a value that is not a status but is instead a message ID for display strings Facility - indicates the system service that is responsible for the status.
Examples: 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 - the facility's status code
Numeric representation
An HRESULT value is sometimes displayed as a hexadecimal value with 8 digits. Examples: 0x80070005 SRCNX , bit field meanings 10000000000001110000000000000101, 0x80070005 , HRESULT as binary and HRESULT as hexadecimal 1..............................., 0x1 , S, Severity, failure (1) .0.............................., 0x0 , R, Reserved ..0............................., 0x0 , C, Customer, Microsoft-defined (0) ...0............................, 0x0 , N, Reserved ....0..........................., 0x0 , X, .....00000000111................, 0x7 , Facility: win32 ................0000000000000101, 0x5 , Code: E_FAULT 0x80090032 0x8 - Status: Failure 0x9 - Facility: SSPI 0x32 - Code: The request is not supported Sometimes an HRESULT value is shown as a signed integer, but this is less common and harder to read.
Name representation
An HRESULT is sometimes represented as an identifier with the format Facility_Severity_Reason: Facility is either the facility name or some other distinguishing identifier Severity is a single letter, S for succeeded or E for error (failed) Reason describes the meaning of the code For example, STG_E_FILENOTFOUND indicates a storage related error, file does not exist. The facility part is omitted if the facility is 0 (FACILITY_NULL) or for some very common values. For example: S_OK, E_FAIL, E_INVALIDARG. This representation is easier to read than a numerical format but is less precise since although based on convention there is no definitive algorithm to convert between value and name.
Using an HRESULT value
Since HRESULT is defined as a signed integer and since the severity field is the most significant bit, a negative value indicates failure and other values indicate success. The most commonly used success code is S_OK which has value 0. However, in rare circumstances, a function returns a success code with additional information such as S_FALSE which has value 1.
When an HRESULT value is displayed as hexadecimal (generally for debugging purposes) a developer can identify a value as indicating failure when it starts with digit 8 or greater in the 8th and most significant place. Note that if not padded to 8 digits with leading zeroes, a value might mistakenly be seen as failure. For example, 80005 is success even though it starts with 8. If padded to 8 digits this becomes clear: 00080005. This is somewhat contrived since generally success is 0 which is clearly a success code.
Programmatic ways to check for failure status are to test for negative or to use a system-defined macro. HRESULT hr = func(...); if (hr = 0) ; // succeeded if (FAILED(hr)) ; // failed if (SUCCEEDED(hr)) ; // succeeded Testing for 0 such as (hr) or (!hr) will work most of the time but is incorrect for the rarely used success codes other than S_OK such as S_FALSE . To obtain the code part of an HRESULT, use the HRESULT_CODE() macro. Use the ERR.EXE tool to translate a value to the corresponding message text.
The ERRLOOK.EXE tool can be used to display error strings associated with a given HRESULT value. It can be run from a Visual Studio command prompt. The win32 SetErrorInfo associates an HRESULT value with a corresponding IErrorInfo object. GetErrorInfo reads this information. The win32 FormatMessage can be used to get a human readable description of some non-IErrorInfo HRESULT values. The winerror.h header file defines some commonly used HRESULT values. HRESULT values are sometimes encoded in the header (.h) files of a subsystem.
These values are also defined in the corresponding header files of the Microsoft Windows Platforms SDK or DDK.
Origin of name
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."
References
Text derived from https://en.wikipedia.org/w/index.php?oldid=1372177733 under CC BY-SA 4.0; modifications have been made.