HRESULT

HRESULT is a 32-bit value used in Windows programming to indicate the result of an operation, most notably in COM interfaces, Win32 APIs, and Windows Runtime components. It encodes both the general outcome (success or failure) and the source of the result in a single value, allowing callers to test and categorize errors efficiently.

The value is laid out with a specific bit structure: bit 31 is the severity (0 for success, 1 for failure); bits 30 through 16 (15 bits) encode the facility, which identifies the subsystem or category that produced the code; and bits 15 through 0 (16 bits) contain the actual status or error code. This design enables a broad range of codes while preserving a compact representation of origin and meaning.

Two common helpers are used with HRESULTs. The macro MAKE_HRESULT(sev, fac, code) constructs a value from a severity, facility, and code. The macros SUCCEEDED(hr) and FAILED(hr) test the most significant bit to determine whether a result indicates success or failure; SUCCEEDED returns true for both S_OK and S_FALSE, while FAILED returns true only for error conditions.

Common values include S_OK (0x00000000), indicating success, and several standard error codes such as E_FAIL (0x80004005), E_ACCESSDENIED (0x80070005), and E_INVALIDARG (0x80070057). The facility field can be used to identify the subsystem, with predefined facilities like FACILITY_WIN32 (7).

HRESULTs are widely used for error reporting in Windows API calls, COM methods, and related technologies. They are typically checked with SUCCEEDED or FAILED, and may be converted to higher-level exceptions if the programming model requires it.