Could you please explain to me the WINAPI word in the WinMain() function?
In the simplest way..
#include <windows.h>
int -->WINAPI<-- WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
LPSTR lpCmdLine, int nCmdShow)
{
MessageBox(NULL, "Goodbye, cruel world!", "Note", MB_OK);
return 0;
}
Is it just some Windows funky mode?
What does it do? Or rather what is this C++ feature I haven't encountered yet?
WINAPI is a macro that evaluates to __stdcall, a Microsoft-specific keyword that specifies a calling convention where the callee cleans the stack. The function's caller and callee need to agree on a calling convention to avoid corrupting the stack.
WINAPI is a macro that expands to __stdcall which means that the callee cleans the stack.
This is a macro definition intended to denote the Windows calling convention. From MSDN:
The way the name is decorated depends
on the language and how the compiler
is instructed to make the function
available, that is, the calling
convention. The standard inter-process
calling convention for Windows used by
DLLs is known as the WinAPI
convention. It is defined in Windows
header files as WINAPI, which is in
turn defined using the Win32
declarator __stdcall.
It's Windows-specific. It specifies the calling convention. WinMain gets called by Windows, and this ensures that the caller and callee agree on the calling convention.
Related
I'm wondering why so many Win API functions are only defines to their real implemenation in MinGW.
Example:
MessageBox() function as described in the MSDN documenation:
int WINAPI MessageBox(
_In_opt_ HWND hWnd,
_In_opt_ LPCTSTR lpText,
_In_opt_ LPCTSTR lpCaption,
_In_ UINT uType
);
And here's the implementation of MinGW (winuser.h):
#define MessageBox MessageBoxA
/* ... */
WINUSERAPI int WINAPI MessageBoxA(HWND,LPCSTR,LPCSTR,UINT);
So MessageBox is not a function, it's only a define for the real function.
Another one (taken from winbase.h:
#define GetVersionEx GetVersionExA
/* ... */
WINBASEAPI BOOL WINAPI GetVersionExA(LPOSVERSIONINFOA);
As you can see in most cases the functions are implemented as macros to their real implementation.
Is there any reason for doing this? And why are they not implemented as "real" functions (using their real name)?
From GetVersionEx documentation:
Unicode and ANSI names: GetVersionExW (Unicode) and GetVersionExA (ANSI)
From Conventions for Function Prototypes documentation:
The preprocessor expands the macro into either the Windows code page or Unicode function name. The letter "A" (ANSI) or "W" (Unicode) is added at the end of the generic function name, as appropriate. The header file then provides two specific prototypes, one for Windows code pages and one for Unicode, as shown in the following examples.
In your case, GetVersionEx will expand to GetVersionExA because it looks like you are using Windows code page.
Using the DEFINEs enable you to use the same code with difference compiler options. For example: MessageBox will use MessageBoxW if using unicode, but MessageBoxA if not. It would be a pain to have to go through an entire code base just to change the method names.
Edit: Also see Christoph's reference, which this answer is referring to.
I'm using \W4 warning level on Visual Studio and I'm writing a Windows program.
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow)
All these parameters are not used in my application, so I get warnings at compile time.
I know there are two ways of dealing with this:
Commenting parameters HINSTANCE /*hInstance*/ ...
Using the UNREFERENCED_PARAMETER macro
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow)
{
UNREFERENCED_PARAMETER(hInstance);
UNREFERENCED_PARAMETER(hPrevInstance);
UNREFERENCED_PARAMETER(lpCmdLine);
UNREFERENCED_PARAMETER(nCmdShow);
Which one is the correct one? Which one is the safer to use? Are there any problems with using the macro?
I would prefer commenting the parameters.
The macro UNREFERENCED_PARAMETER is defined in winnt.h and therefore not portable.
And if later you do reference it, you might overlook to remove the macro.
Edit: With C++17 you can now use the [[maybe_unused]] attribute. This is useful for code depending on preprocessor macros:
void foo( [[maybe_unused]] int value )
{
#ifdef USE_VALUE
useValue(value);
#endif
}
Now there won't be warnings even if USE_VALUE is undefined.
I consider the name-removing version the first to go with. It can have a disadvantage to confuse the information system so tooltip shows the crippled version. But healthy ones would use the declaration, where the names are there. (and for static and one-use things you should not have unused params, right?)
Otherwise it's matter of taste really.
In C++, both are the correct ways to handle and do not introduce any unsafe-ness directly. However, the use of UNREFERENCED_PARAMETER can cause a maintenance issue because you need to remove the use of the macro if the parameter is used in the future updates, yet compilers do not warn that situation. To audit correct use of the macro, developers have to manually inspect that the parameters are still unused.
As others pointed out, cross-platform portability could be an issue too.
In C, it is not possible to remove the parameter name; hence the macro is the reasonable solution on the Windows platform, especially in Win32 programming.
I am learning about C++ and programming to the windows api. My first "Hello Windows API" program just displays a MessageBox(). But, I have questions that the book I'm reading isn't explaining.
First, here's the program:
// HelloWin32 Program
#include<Windows.h>
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nShowCmd)
{
MessageBox(NULL, "This gets displayed in the message.", "This is the title bar of the message dialog.", MB_OK | MB_ICONEXCLAMATION);
}
This compiles and runs fine. My question has to do with the WinMain() declaration that says int WINAPI WinMain(...). As I read it, the WinMain function (method?) returns an integer. But what does WINAPI communicate?
Obviously, I'm writing to the Windows API. Does WINAPI somehow flag the function so the program uses Windows API to execute it or something?
WINAPI is a preprocessor definition defined as __stdcall, a calling convention; when functions have __stdcall before their name, it is a directive to the compiler to make the function use that calling convention. This is so both your function and the function calling your function agree to use the stdcall calling convention and the call executes correctly.
This is necessary because the default calling convention of your compiler may or may not be stdcall, so you have to explicitly tell the compiler to make it that way for that function. The designers of the Windows API decided, mainly for compatibility reasons and the universality of the stdcall calling convention, to make all function calls use the stdcall calling convention.
Also, you can have functions with different calling conventions being used in the same program. So for instance, WinMain has to be stdcall but the other functions of your program do not; they can use the compiler default.
A calling convention is a method for doing things like the order in which parameters should go on the stack, who should remove them from the stack when the function returns, where to put return values, and other things. Different calling conventions do this in different ways. Above all, it is extremely important that both the caller and the callee follow the same calling convention. For more info on calling conventions, see the Wikipedia article.
For example:
int WINAPI WinMain ( HINSTANCE instance, HINSTANCE prev_instance, PSTR cmd_line, int cmd_show )
WINAPI is a a define that looks like this:
#define WINAPI __stdcall
why can't you just do:
int __stdcall WinMain ( HINSTANCE instance, HINSTANCE prev_instance, PSTR cmd_line, int cmd_show )
actually I think my problem is that I'm sort of confusing defines with typedef's. Can someone explain this to me? what does the define do and why can't you just write __stdcall in its place?
Because the WINAPI calling convention is not guaranteed to be __stdcall. Code that uses WINAPI will still be correct even when it isn't.
You can write the function as in your latter example, and it'd work fine - it's just not good practice and would not be portable to a platform where the calling convention is something else.
This was originally done during the switchover from 16-bit to 32-bit code. In the 16-bit version of <windows.h> it was:
#define WINAPI __pascal
WINAPI let you compile for either without modifying the source code. Of course, 16-bit Windows is no longer a factor (at least for most people), but it's still not worth changing all the source code to use __stdcall directly (especially since it could change again someday).
You can just write __stdcall in its place, but don't. They've seen fit to #define WINAPI to __stdcall to make that opaque, which is just good programming practice.
Also, back in the day, some Windows libraries used Pascal calling convention and other libraries used C convention. A preprocessor define helped gloss over that.
Because WINAPI is a macro (well a #define anyway) it can be "pre-processed" to mean something else or even nothing at all.
That means you can write more portable code, as you can put in WINAPI when it is required by Win32 to mean __stdcall but, or if it is required in another environment to mean something else or nothing.
Just to experiment assembly in C++, I tried the following, which is causing the application to crash:
int APIENTRY _tWinMain(HINSTANCE hInstance,
HINSTANCE hPrevInstance,
LPTSTR lpCmdLine,
int nCmdShow)
{
__asm {
push 5000
call Sleep
}
...
}
the assembly part of code is supposed to act like the following line
Sleep(5000);
What am I doing wrong?
edit: I am getting an Access Violation.
I just checked the assembly code in VC++ 6.
You have to call the routine like this:
call dword ptr [Sleep]
Write the code in straight in C - disassemble it, figure out what the compiler does, then you can write a correct version -
I am not x86 guy, but I think you should check the calling convention used by the compiler. It seems that Sleep cleans after it self, so maybe the compiler is inserting cleaning code also after that?
It's been a long time since I did this but I recall from the past that sometimes I had to put a single parameter in the EAX register rather than push it on the stack. Or perhaps you need to pop it off again after words if the calling convention requires it.
As Arak says, check that you are matching the compiler calling convention. Masm will force one convention, check your C compiler is enforcing the same.