Edit

Error Handling in COM (COM)

Almost all COM functions and interface methods return a value of the type HRESULT. The HRESULT (the name can be read as "result handle") is a way of returning a success, warning, or error value. A HRESULT is actually not a handle (see Why does HRESULT begin with H when it's not a handle to anything?); it's just a value with several fields encoded into it. As per the COM specification, a result of zero indicates success, and a nonzero result indicates failure.

Important

Always check HRESULT return values. Never ignore the return value of a COM function. Use the FAILED() and SUCCEEDED() macros (defined in <winerror.h>) — do not compare directly against S_OK, because success codes other than S_OK exist (for example, S_FALSE):

// ✅ Correct — handles all failure codes
HRESULT hr = pStream->Read(buffer, cbSize, &cbRead);
if (FAILED(hr)) {
    // Handle error
    return hr;
}

// ❌ Wrong — misses failure codes that aren't E_FAIL
if (hr == E_FAIL) { ... }

// ❌ Wrong — S_FALSE is success but != S_OK
if (hr != S_OK) { /* this fires for S_FALSE too */ }

Modern helpers for error handling:

  • THROW_IF_FAILED(hr) — Windows Implementation Libraries (wil) throws a C++ exception on failure
  • winrt::check_hresult(hr) — C++/WinRT equivalent, throws winrt::hresult_error
  • LOG_IF_FAILED(hr) — wil macro that logs on failure but continues execution

At the source code level, all error values consist of three parts, separated by underscores. The first part is the prefix that identifies the facility associated with the error, the second part is E for error, and the third part is a string that describes the actual condition. For example, STG_E_MEDIUMFULL is returned when there is no space left on a hard disk. The STG prefix indicates the storage facility, the E indicates that the status code represents an error, and the MEDIUMFULL provides specific information about the error. Many of the values that you might want to return from an interface method or function are defined in Winerror.h.

For more information about error handling, see the following sections:

COM Error Codes

 

 

  • Last updated on