• __cdecl dictates that the caller removes parameters from the stack. This makes it possible to create functions with variable arguments, since only the caller knows how many parameters were put on the stack in the first place.
• __stdcall dictates that the callee removes the parameters from the stack. This prohibits variable length parameter lists since the callee only knows how many parameters to pop if the parameter list was fixed curing compilation. __stdcall is also the calling convention that is used by the Windows platform itself. Any function that is exported from a DLL and uses this convention can be used by any programming language that runs on the Windows platform simply because that is the convention that is used for the system DLLs.
• __fastcall uses both the stack and registers to pass parameters. It is the one and only convention that is used by Windows and the VC++ compiler for 64 bit platforms.

For 32 bit environments, the best option would be to use __stdcall because anything that runs on the Windows platform can use it.

If you really need variable length arguments, you have to use __cdecl, but there are few valid reasons for such functions. They are dangerous to use because any mistake in using them has the potential to crash an application or destabilize the system.

For a 64 bit environment you will use __fastcall, but you don't specify it because the compiler does not allow you to. Any calling convention you specify will be ignored. Therefore it is best not to specify anything to avoid confusion.

If you do not specify a calling convention, you'll get the default of your C++ environment. In a default installation of VC++ this is __cdecl. You don't want to rely on it though, because different environments might have different default configurations, and __cdecl is not what you want to use anyway.

Since the same declaration will be compiled for both 32 and 64 bit environment, a macro has to be used to facilitate this.

1. For 64 bit builds, the calling convention is empty. For 32 bit builds the calling convention is defined to be __stdcall. That way we get clean builds in all configurations.
2. Declare functions that will eventually be exported.

#ifdef  _WIN64                        //1
#define FOO_DLL_CALLCONV 
#else
#define FOO_DLL_CALLCONV __stdcall
#endif
void CALLCONV foo();                  //2

This way, function 'foo' will have the correct calling convention while at the same time removing the calling convention specification for 64 bit builds.

C vs C++: What's In A Name
A common problem with DLL is this: You're compiling a program, and at the linking stage you link against the import lib file of a certain DLL that exports a function 'foo'.

You get a linker error that indicates that the linker cannot find function 'foo', despite the fact that you know for certain it exists and is exported.

What's happened is that when the exported function was compiled, its name was decorated or 'mangled' by the C++ compiler.

C++ allows function overloading, where different functions can have the same name but a different parameter list.

Such functions cannot have the exact same name or there would be a naming conflict. That is why the types in the parameter list are encoded in the name of the function. For example, the function 'foo' might have the name 'foo@@YAHNHPA_W@Z' in the resulting object file.

In C this is not the case. C assumes that a function named 'foo' will still be the only one called 'foo'. C never needed name decoration to support its language features.

Since this feature of C++ makes it very hard to properly use the DLL in a C environment, or any other environment that requires us  to specify a function by its true name, we have to prevent this from happening.

We solve this with the following construction:

#ifdef __cplusplus
extern "C"{
#endif

void CALLCONV foo();

#ifdef __cplusplus
}
#endif

The __cplusplus macro is always defined when a C++ compiler is invoked. In this case the function 'foo' is declared as a function that has to be compatible with C linkage rules using the extern 'C" statement.

Putting It All Together
Finally, all the elements are in place to make a proper function declaration. For this example we declare a function that prints a text string in a user supplied buffer.

1. Prevent symbol names from getting mangled C++ style.
2. Define the calling convention for our DLL.
3. Our hypothetical function takes a string buffer as a parameter. If we want to support both ANSI and Unicode, we have to implement 2 distinct functions. This also means that the pseudo name 'foo' can only be use in C or C++ environments. Environments that need the programmer to specify the function foo by name need to use fooA or fooW.
4. Declare fooA.

declare fooW
#ifdef __cplusplus                    //1
extern "C" {
#endif

#ifndef _WIN64                        //2
#define DLL_CALLCONV  __stdcall
#else
#define DLL_CALLCONV
#endif

#ifdef UNICODE                        //3
#define foo  fooW
#else
#define foo  fooA
#endif
int DLL_CALLCONV fooA(wchar_t *Buffer, size_t BufferSize );     //4
int DLL_CALLCONV fooW(char *Buffer, size_t BufferSize );     //5

#ifdef __cplusplus
}
#endif

As you can see, once you know what the different pieces of the puzzle look like, assembling it is not a big deal.

Conclusion
This article lays down the ground rules of what a function declaration should look like if that function has to be exported from the DLL later on.  My next article will discuss the 'how' of function exports.

Bruno van Dooren is a systems engineer for Genzyme Flanders and a Microsoft MVP, specializing in Visual C++.  He can be reached at bruno_van_dooren@hotmail.com. He also maintains a blog at www.msmvps.com/blogs/vanDooren where he blogs about topics related to C++ and the Windows platform.