Deciphering an HRESULT

Heath Stewart

July 21st, 20050 0

Aaron Stebner recently blogged about ways to find out the cause of 1935 Windows Installer errors and I wanted to provide a little more background on what an HRESULT defines.

An HRESULT in the 32-bit world and beyond is defined as a long, or a signed 32-bit integer. It is defined in, among other places, winerror.h in the Platform SDK. It defines the severity of an error, whether the error is from user code, a facility that defines where the error came from, and the actual error code. As defined in winerror.h:

//  Values are 32 bit values layed out as follows:
//
//   3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
//   1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
//  +---+-+-+-----------------------+-------------------------------+
//  |Sev|C|R|     Facility          |               Code            |
//  +---+-+-+-----------------------+-------------------------------+
//
//  where
//
//      Sev - is the severity code
//
//          00 - Success
//          01 - Informational
//          10 - Warning
//          11 - Error
//
//      C - is the Customer code flag
//
//      R - is a reserved bit
//
//      Facility - is the facility code
//
//      Code - is the facility's status code

Return codes like S_OK and S_FALSE have the values 0 and 1, respectively. S_FALSE is not treated as an error because the severity bits are 0. Return codes like E_FAIL have the error bit set to 1 (the high-order bit). The macro HRESULT_SEVERITY can help determine if the return code represents an error or not by performing a bitwise AND on the high-order bit.

A facility helps identify from where the error came. Was it a security error or an error from the Common Language Runtime (CLR)? The macro HRESULT_FACILTY can help you determine that as well. winerror.h defines the following facilities (sorted by value):

#define FACILITY_NULL                    0
#define FACILITY_RPC                     1
#define FACILITY_DISPATCH                2
#define FACILITY_STORAGE                 3
#define FACILITY_ITF                     4
#define FACILITY_WIN32                   7
#define FACILITY_WINDOWS                 8
#define FACILITY_SSPI                    9
#define FACILITY_SECURITY                9
#define FACILITY_CONTROL                 10
#define FACILITY_CERT                    11
#define FACILITY_INTERNET                12
#define FACILITY_MEDIASERVER             13
#define FACILITY_MSMQ                    14
#define FACILITY_SETUPAPI                15
#define FACILITY_SCARD                   16
#define FACILITY_COMPLUS                 17
#define FACILITY_AAF                     18
#define FACILITY_URT                     19
#define FACILITY_ACS                     20
#define FACILITY_DPLAY                   21
#define FACILITY_UMI                     22
#define FACILITY_SXS                     23
#define FACILITY_WINDOWS_CE              24
#define FACILITY_HTTP                    25
#define FACILITY_BACKGROUNDCOPY          32
#define FACILITY_CONFIGURATION           33

All facilities except for FACILITY_ITF are defined by Microsoft. FACILITY_ITF is designated for user-defined error codes returned from interface methods. Microsoft recommends that when using FACILITY_ITF you use errors in the range of 0x0200 to 0xffff.

One might be asking if the 2 high-order bits define the severity and having both set is an error, why – in hexadecimal – does the error code number start with 8 instead of C? In the days of 16-bit computing, an HRESULT was only a 16-bit signed integer while an SCODE was a 32-bit signed integer. Only the highest-order bit designated the severity. The facility was also only 4 bits instead of 11. Error codes such as E_FAIL defined as 0x80004005 are legacy SCODEs and the values have not changed. Newer error codes may set both severity bits like ERROR_AUDITING_DISABLED defined as 0xC0090001.

Hopefully this helps you to decipher error codes and at least get some idea from where the error came.

Edit: Thanks to bgrainger for pointing out the correct recommended range.