Handling WinAPI error return values

Question

I am currently learning C++ in connection with WinAPI. I am struggling to come up with meaningful error handling strategy for WinAPI functions.

PROBLEM:

Most of WinAPI functions can return 0 in case of error, but in many cases I don't see any information on MSDN as to what could cause such error and how to address / resolve it. Taking GetCursorPos as an example:

Returns nonzero if successful or zero otherwise. To get extended error information, call GetLastError.

(...)

The input desktop must be the current desktop when you call GetCursorPos. Call OpenInputDesktop to determine whether the current desktop is the input desktop. If it is not, call SetThreadDesktop with the HDESK returned by OpenInputDesktop to switch to that desktop.

If I follow the route of GetLastError I am interested in what errors could be returned by that specific function so that I can inspect what can be done about them. But error codes are organized on this MSDN page into 10 groups based on just error number and without any specification of what errors are listed in which group.
When I tried to discover how would OpenInputDesktop help me make my code more bulletproof I discovered that again:

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

To sum it up: almost every function in WinAPI can return value determining occurrence of error and I can get information on the error when it happens using GetLastError function. But no information whatsoever on what kinds of errors I can expect and what steps to make to resolve them.

The examples are many, GetWindowRect is also widely used and MSDN delivers the very same limited information as for GetCursorPos.

QUESTION:

Please are there any standards on how to approach WinAPI function error return values that would retain error handling from becoming just showing a message box and exiting the application? Thank you!

In case of both GetWindowRect and GetCursorPos, you only call GetLastError if one of those APIs return FALSE. — Asesh
@Asesh Yes, but that only gives me information on what error happened and only when it happens. MSDN is very limited resource in regards to what errors can happen so that I can better understand/decide what my code should do in such case. — Xzsh4s575sf75
Unless documentation for a given API function explicitly states specific error codes that are returned, then you can't rely on particular errors because ANY error could be returned. In those cases, you are not supposed to try to recover from them, since you can't know ahead of time why they are failing. You can only possibly recover from known errors. If the API is essential for a given operation to succeed, all you can do it fail the operation, optionally log the error, and move on — Remy Lebeau
retain error handling from becoming just showing a message box and exiting the application - This dependes on how critical each particular error is for your application. In some cases, you may simply skip the code that depends on the failed API (e. g. GUI drawing code), in other cases you may log the error but without informing the user and for mission-critical APIs you will show an error message in addition to logging. I think your question is too broad to answer specifically. — zett42
The question essentially boils down to this: How do you transfer control from the point of error discovery to the point of (potential) error handling? C++ uses exceptions for this, std::system_error being the most appropriate one in this case. This is necessary, because you generally do not know anything about the implications of an error at the point where it's discovered. The old "use exceptions in exceptional situations only" doesn't buy you anything, because at the point where you have to decide, you cannot assess whether this is exceptional or not. — IInspectable

mnistic mnistic · Accepted Answer · 2017-10-21T21:08:36

As far as knowing ahead of time what possible error codes can be returned by a particular function, I'm afraid that Microsoft decided long time ago that maintaining such documentation for all functions would be too cumbersome and costly, as an API function may call any number of other API functions, which in turn may call others and so on. Sometimes you get lucky and the MSDN doc calls out error codes specific to that function, as is the case with ReadFile but this is not the case with all functions as you have noticed.

That being said, the standard way of dealing with the error codes returned by GetLastError() is to format them with FormatMessage.

If you passed LANG_USER_DEFAULT for lang ID, this will return the sometimes helpful, sometimes not so helpful error message formatted in the user's chosen locale from the error code. You can show this message to the user. If you wanted to format it in your own language for logging purposes, assuming it's English, you would pass MAKELANGID(LANG_ENGLISH, SUBLANG_ENGLISH_US) for lang ID.

And this is the best you can do if the error codes are not documented and you haven't come across them in testing: log them and get the log with other debug info attached to the issue report.

Handling WinAPI error return values

1 Answers