Microsoft Learn

Error Handling in Windows API

Effective error handling is crucial for developing robust and reliable applications on Windows. The Windows API provides several mechanisms for reporting and handling errors that occur during API function calls.

Error Reporting Mechanisms

Most Windows API functions that can fail return a value indicating success or failure. The specific return value varies by function, but common conventions include:

• Returning a non-zero value for success and zero for failure (e.g., CreateProcess).
• Returning a pointer to a structure for success and NULL for failure (e.g., CreateFile).
• Returning a status code indicating success or a specific error (e.g., NTSTATUS codes).

Retrieving Error Information

When an API function fails, you can typically retrieve detailed error information using the GetLastError function. This function returns the last error code set by the calling thread. The error codes are defined in WinError.h.

To convert the error code into a human-readable string, you can use the FormatMessage function:

Here's a typical pattern for checking and retrieving errors:

#include <windows.h>
#include <iostream>

// Assume some API function call fails
BOOL success = MyApiFunction();

if (!success) {
    DWORD error = GetLastError();
    LPSTR messageBuffer = nullptr;
    size_t size = FormatMessageA(
        FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,
        NULL, error, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), (LPSTR)&messageBuffer, 0, NULL);

    std::cerr << "API call failed with error code: " << error << std::endl;
    std::cerr << "Error message: " << messageBuffer << std::endl;

    LocalFree(messageBuffer); // Free the buffer allocated by FormatMessage
}
            

Common Error Codes

• ERROR_SUCCESS (0): The operation completed successfully.
• ERROR_INVALID_FUNCTION (1): Incorrect function.
• ERROR_FILE_NOT_FOUND (2): The system cannot find the file specified.
• ERROR_ACCESS_DENIED (5): Access is denied.
• ERROR_INVALID_PARAMETER (87): The parameter is incorrect.
• ERROR_NOT_ENOUGH_MEMORY (8) / ERROR_OUTOFMEMORY (14): Not enough memory is available to complete this operation.

Refer to the WinError.h documentation for a comprehensive list of error codes.

Error Handling Strategies

• Check Return Values: Always check the return value of API functions.
• Use GetLastError: Retrieve detailed error information when a function fails.
• Provide User Feedback: Display meaningful error messages to the user.
• Log Errors: Record errors for debugging and monitoring purposes.
• Graceful Degradation: If possible, allow the application to continue functioning with reduced capabilities rather than crashing.