HRESULTs

HRESULT is a 32-bit value used by Windows APIs, most notably COM, to indicate success or failure and to convey additional error information. Functions that follow the Windows API convention typically return an HRESULT, allowing callers to test results uniformly.

The value encodes three pieces of information: severity, facility, and code. The most significant bit (bit 31) is the severity: 0 indicates success or informational, 1 indicates failure. The facility field (bits 16 through 27) identifies the system area that generated the error (for example, the Windows subsystem or a particular component). The low 16 bits (bits 0 through 15) carry a facility-specific status code. While many codes are negative in signed interpretation, the essential rule is that nonnegative values are success, and negative values indicate failure.

Common usage patterns include test macros such as SUCCEEDED(hr) and FAILED(hr), which check the sign of the value rather than matching against a specific code. In practice, many programs return S_OK (0x00000000) for success or S_FALSE (0x00000001) for a non-error informational result, while various E- prefixed values denote errors. Widely seen codes include E_FAIL (0x80004005) and E_INVALIDARG (0x80070057); E_ACCESSDENIED (0x80070005) and E_OUTOFMEMORY (0x8007000E) are also common. The exact code is often interpreted along with the facility to determine the subsystem that produced the error.

Two important helper mechanisms are available: MAKE_HRESULT and HRESULT_FROM_WIN32. MAKE_HRESULT constructs an HRESULT from severity, facility, and code, while HRESULT_FROM_WIN32 maps a Win32 error into an HRESULT with FACILITY_WIN32. In .NET and other environments, HRESULT failures often translate to exceptions during interop.

See also: SUCCEEDED and FAILED macros, MAKE_HRESULT, HRESULT_FROM_WIN32, facilities and common HRESULT values.

---