Windows API Reference

These are some of the most frequently encountered status codes.

S_OK

The operation completed successfully. This is the most common success code.

E_FAIL

An unspecified error occurred. This is a generic failure code and should ideally be accompanied by more specific error information if available.

E_INVALIDARG

One or more arguments were invalid. This indicates that a function was called with parameters that do not meet its requirements.

E_OUTOFMEMORY

Not enough memory is available to complete the operation. This error can occur when allocating resources.

E_POINTER

A pointer is invalid. This often means a null pointer was passed where a valid pointer was expected.

E_UNEXPECTED

An unexpected error occurred. This is often used for internal errors or conditions that should not have happened.

E_NOTIMPL

The requested operation is not implemented. This is commonly returned by stubs or interfaces that have not yet been fully developed.

WAIT_TIMEOUT

The timeout interval elapsed before the object became signaled. This is common for functions that wait for an event.

Windows uses a 32-bit structure called an HRESULT to represent status codes. It encodes information about the severity, facility, and error code.

The structure of an HRESULT is as follows:

• Bit 31: Severity (0 for success, 1 for error)
• Bits 16-30: Facility code
• Bits 0-15: Error code

The facility code indicates the source or module that generated the error. Some common facilities include:

• FACILITY_NULL (0): Not a real facility.
• FACILITY_RPC (1): Remote Procedure Call
• FACILITY_DISPATCH (2): COM dispatch
• FACILITY_STORAGE (3): Storage
• FACILITY_Win32 (7): Win32 error codes
• FACILITY_Windows (8): Windows system errors
• FACILITY_UserDefined (64): User-defined errors

When calling a Windows API function, you typically check the HRESULT return value to determine success or failure.

    HRESULT hr = SomeFunctionThatMightFail();

    if (SUCCEEDED(hr)) {
        // Operation was successful
        // ...
    } else {
        // Operation failed
        // You can use FAILED(hr), HRESULT_CODE(hr), or HRESULT_FACILITY(hr)
        // to extract more information.
        // For Win32 errors, you might use FormatMessage to get a string.
        if (HRESULT_FACILITY(hr) == FACILITY_Win32) {
            DWORD win32Error = HRESULT_CODE(hr);
            // Handle Win32 error
        } else {
            // Handle other HRESULT errors
        }
    }
                

• Error Handling in Windows
• WinError.h Header
• COM Error Objects