CreateDIBSection: Return value vs error

Question

The documentation of CreateDIBSection states:

If the function succeeds, the return value is a handle to the newly created DIB, and *ppvBits points to the bitmap bit values.

If the function fails, the return value is NULL, and *ppvBits is NULL.

However, directly after that it states:

This function can return the following value [...] ERROR_INVALID_PARAMETER

So, what is meant by this last sentence? I can hardly imagine that it really returns that value (possibly it actually calls SetLastError). Is this somewhere thoroughly documented?

Answer 1

This is simply an error in the current version of the documentation!

The CreateDIBSection always returns an HBITMAP. If the function fails, then it will return 0 (NULL), and you can call GetLastError. GetLastError will return ERROR_INVALID_PARAMETER.

This is the standard way that all GDI functions work, not to mention the fact that it is impossible for a function return both NULL and an error code. I was also able to dig up an old version of the MSDN documentation for this function (circa 2008), and it confirms that the current version of the online documentation is indeed erroneous: