HRESULT
Encyclopedia
In the field of computer programming
, the HRESULT is a data type
used in many types of Microsoft
technology. HRESULTs are used as function parameters
and return values to describe errors and warnings in a program.
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.
throws an exception, the runtime
passes the HRESULT to the COM
client. When unmanaged code returns an error, the HRESULT is converted to an exception, which is then thrown by the runtime.
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 SUCCEEDED 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 FormatMessage API function can be used to convert an HRESULT into a user-readable string.
Computer programming
Computer programming is the process of designing, writing, testing, debugging, and maintaining the source code of computer programs. This source code is written in one or more programming languages. The purpose of programming is to create a program that performs specific operations or exhibits a...
, the HRESULT is a data type
Data type
In computer programming, a data type is a classification identifying one of various types of data, such as floating-point, integer, or Boolean, that determines the possible values for that type; the operations that can be done on values of that type; the meaning of the data; and the way values of...
used in many types of Microsoft
Microsoft
Microsoft Corporation is an American public multinational corporation headquartered in Redmond, Washington, USA that develops, manufactures, licenses, and supports a wide range of products and services predominantly related to computing through its various product divisions...
technology. HRESULTs are used as function parameters
Parameter (computer science)
In computer programming, a parameter is a special kind of variable, used in a subroutine to refer to one of the pieces of data provided as input to the subroutine. These pieces of data are called arguments...
and return values to describe errors and warnings in a program.
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.
HRESULT format
HRESULTs are organized as follows:| 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.
- Facility - indicates the system service that is responsible for the error. Example facility codes are shown below (for the full list see ).
- 1 - RPCRemote procedure callIn computer science, a remote procedure call is an inter-process communication that allows a computer program to cause a subroutine or procedure to execute in another address space without the programmer explicitly coding the details for this remote interaction...
- 2 - Dispatch
- 3 - Storage
- 4 - ITF
- 7 - Win32
- 8 - Windows
- 9 - SSPISecurity Support Provider InterfaceSecurity Support Provider Interface is an API used by Microsoft Windows systems to perform a variety of security-related operations such as authentication....
- 10 - Control
- 11 - CERT
- ...
- 1 - RPC
- Code - is the facility's status 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. When managed codeManaged code
Managed code is a term coined by Microsoft to identify computer program code that requires and will only execute under the "management" of a Common Language Runtime virtual machine ....
throws an exception, the runtime
Run-time system
A run-time system is a software component designed to support the execution of computer programs written in some computer language...
passes the HRESULT to the COM
Component Object Model
Component Object Model is a binary-interface standard for software componentry introduced by Microsoft in 1993. It is used to enable interprocess communication and dynamic object creation in a large range of programming languages...
client. When unmanaged code returns an error, the HRESULT is converted to an exception, which is then thrown by the runtime.
Using HRESULTs
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 SUCCEEDED 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 FormatMessage API function can be used to convert an HRESULT 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"