9.3.5.3 Stdcall Calling Convention

This convention, which was the calling convention used for Pascal programs, is used by Microsoft for all the routines in the Win32 API for efficiency reasons. It must be used to import any routine for which this convention was specified.

In the Stdcall calling convention subprogram parameters are pushed on the stack by the caller from right to left. The callee (and not the caller) is in charge of cleaning the stack on routine exit. In addition, the name of a routine with Stdcall calling convention is mangled by adding a leading underscore (as for the C calling convention) and a trailing @`nn', where nn is the overall size (in bytes) of the parameters passed to the routine.

The name to use on the Ada side when importing a C routine with a Stdcall calling convention is the name of the C routine. The leading underscore and trailing @`nn' are added automatically by the compiler. For instance the Win32 function:

    APIENTRY int get_val (long);

should be imported from Ada as follows:

    function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
    pragma Import (Stdcall, Get_Val);
    --  On the x86 a long is 4 bytes, so the Link_Name is "_get_val@4"

As for the C calling convention, when the External_Name parameter is missing, it is taken to be the name of the Ada entity in lower case. If instead of writing the above import pragma you write:

    function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
    pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val");

then the imported routine is _retrieve_val@4. However, if instead of specifying the External_Name parameter you specify the Link_Name as in the following example:

    function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
    pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val");

then the imported routine is retrieve_val, that is, there is no decoration at all. No leading underscore and no Stdcall suffix @`nn'.

This is especially important as in some special cases a DLL's entry point name lacks a trailing @`nn' while the exported name generated for a call has it.

It is also possible to import variables defined in a DLL by using an import pragma for a variable. As an example, if a DLL contains a variable defined as:

    int my_var;

then, to access this variable from Ada you should write:

    My_Var : Interfaces.C.int;
    pragma Import (Stdcall, My_Var);

Note that to ease building cross-platform bindings this convention will be handled as a C calling convention on non-Windows platforms.