What is the correct return value of the BCM_SETSHIELD Windows API message?

Question

What is the correct return value of the BCM_SETSHIELD message?

The documentation at https://learn.microsoft.com/en-us/windows/win32/controls/bcm-setshield states that it returns 1 on success and an error code otherwise, but in my tests it seems to return 0 when successfully setting the shield.

The documentation for the Button_SetElevationRequiredState macro states it returns void, but the actual implementation returns LRESULT.

The documentation for the MFC CButton (https://learn.microsoft.com/en-us/cpp/mfc/reference/cbutton-class?view=msvc-170) states that there is a method CButton::SetElevationRequired that returns BOOL.

But there is no such method. Instead there is a method CButton::SetShield that returns a HICON.

Answer 1

After more research it turns out that the most correct is the MFC implementation.

BCM_SETSHIELD returns the icon handle of the previous image (if any), similar to what BM_SETIMAGE does.

So, on first call it most likely will return NULL, and on subsequent calls for the same button it will return a handle.

There seems no possibility of an error value being returned.