Why did Microsoft define WINAPI, CALLBACK, and APIENTRY to all refer to __stdcall?

Question

This is a curiosity question for anybody who has worked for, known somebody who's worked for, or otherwise had any sort of affiliation with the Microsoft team responsible for defining these macros.

I understand what __stdcall is and I know why it's used, I just don't understand why Microsoft would make three separate macros for the same thing. The only benefit I could see would be to provide some semantic meaning in a source file, but other than that it provides no other benefit as far as I can tell. Obviously there was a point to doing it, I just want to know what it is! :)

Answer 1

It seems you're right about the different macros being used to provide semantic information. MSDN says this about CALLBACK:

CALLBACK, WINAPI, and APIENTRY are all used to define functions with the __stdcall calling convention. Most functions in the Windows API are declared using WINAPI. You may wish to use CALLBACK for the callback functions that you implement to help identify the function as a callback function.

Both WINAPI and APIENTRY are said to be:

The calling convention for system functions.

I don't know why there's two macros for system functions.

Answer 2

The link to ooga's answer is https://learn.microsoft.com/en-us/windows/win32/winprog/windows-data-types

More details are provided by Microsoft at 'Understanding SAL':

"The Microsoft source-code annotation language (SAL) provides a set of annotations that you can use to describe how a function uses its parameters, the assumptions that it makes about them, and the guarantees that it makes when it finishes. The annotations are defined in the header file <sal.h>. Visual Studio code analysis for C++ uses SAL annotations to modify its analysis of functions. For more information about SAL 2.0 for Windows driver development, see SAL 2.0 Annotations for Windows Drivers.

Natively, C and C++ provide only limited ways for developers to consistently express intent and invariance. By using SAL annotations, you can describe your functions in greater detail so that developers who are consuming them can better understand how to use them."