Tutorial by Examples

The Windows API is provided by means of a C-callable interface. Success or failure of an API call is reported strictly through return values. Exceptions aren't part of the documented contract (although some API implementations can raise SEH exceptions, e.g. when passing a read-only lpCommandLine arg...

Some API calls return a single failure/success flag, without any additional information (e.g. GetObject): if ( GetObjectW( obj, 0, NULL ) == 0 ) { // Failure: no additional information available. }

In addition to a failure/success return value, some API calls also set the last error on failure (e.g. CreateWindow). The documentation usually contains the following standard wording for this case: If the function succeeds, the return value is <API-specific success value>. If the function...

Some API calls can succeed or fail in more than one way. The APIs commonly return additional information for both successful invocations as well as errors (e.g. CreateMutex). if ( CreateMutexW( NULL, TRUE, L"Global\\MyNamedMutex" ) == NULL ) { // Failure: get additional information. ...

HRESULTs are numeric 32-bit values, where bits or bit ranges encode well-defined information. The MSB is a failure/success flag, with the remaining bits storing additional information. Failure or success can be determined using the FAILED or SUCCEEDED macros. HRESULTs are commonly used with COM, but...

GetLastError returns a numerical error code. To obtain a descriptive error message (e.g., to display to a user), you can call FormatMessage: // This functions fills a caller-defined character buffer (pBuffer) // of max length (cchBufferLength) with the human-readable error message // for a Win32 ...