windows,main

http://zetcode.com/gui/winapi/main/

---

Home  Contents

Main functions

In this part of the Winapi tutorial, we will talk about main functions.

The main() function prototypes

The main() function is an entry point to a C program. However, it is not the first program to run. When the entry point is main(), the program execution actually begins in a function called mainCRTStartup(). This function is located in the C runtime library. It initializes things like the memory manager, file I/O support, and the argv parameter. After that, the mainCRTStartup() function will call the main() function.

int main(void);
int main(int argc, char **argv);
int main(int argc, char *argv[]);

These are the function prototypes for the main() function for the classic console program.

#include <stdio.h>
#include <stdlib.h>

int main(int argc, char **argv) 
{
    puts("This is a classic C program.");

    return EXIT_SUCCESS;
}

The above source code presents an example of a classic C program.

The wmain function prototypes

The previous main function prototypes could receive only ASCII characters. If we want a program that could receive wide characters from the command line, we will use the wmain function prototypes.

int wmain(void);
int wmain(int argc, wchar_t **argv);
int wmain(int argc, wchar_t *argv[]);

The above wmain function prototypes take wchar_t characters on the command line. When we use these prototypes, the execution begins in a function called wmainCRTStartup() which will later call the wmain() function.

#include <windows.h>
#include <wchar.h>

int wmain(int argc, wchar_t **argv) 
{
    PDWORD cChars = NULL;
    HANDLE std = GetStdHandle(STD_OUTPUT_HANDLE);   
    
    if (std == INVALID_HANDLE_VALUE) {
        wprintf(L"Cannot retrieve standard output handle
 (%d)", 
            GetLastError());
    }
 
    WriteConsoleW(std, argv[1], wcslen(argv[1]), cChars, NULL);
 
    return EXIT_SUCCESS;
}

We have a wmain() function which can receive wide characters. The example prints the first argument of the console program.

int wmain(int argc, wchar_t **argv) {

The wchar_t type of the second parameter of the wmain() function tells us, that the program input is in wide characters.

HANDLE std = GetStdHandle(STD_OUTPUT_HANDLE);    

The GetStdHandle() function returns a handle to a standard output.

if (std == INVALID_HANDLE_VALUE) {
    wprintf(L"Cannot retrieve standard output handle
 (%d)", 
        GetLastError());
} 

In case of an error, we receive a INVALID_HANDLE_VALUE return code. For this situation we print an error message.

WriteConsoleW(std, argv[1], wcslen(argv[1]), cChars, NULL);

We use the WriteConsoleW() function to write to console in wide characters.

C:winapiexamples2systemMain2>Main2.exe компилятор
компилятор

We add a russian word (compiler) as a parameter to our program. The program simply prints the parameter back to the console. Note that in order to see correct characters, we need to change the default font of the console to Lucida Console. We need a true type font to display wide characters correctly.

The _tmain function prototypes

The _tmain() function is a Microsoft extension. It enables programmers to easily create both ANSI and UNICODE builds of their programs. It is a C macro that translates to wmain() or main()functions, depending whether the _UNICODE constant is defined or not. It was common in the past to create both ANSI and UNICODE builds. Nowadays, many programmers recommend to create only unicode programs. This is also what we will do in our tutorial. We will create mostly unicode programs.

int _tmain(void);
int _tmain(int argc, TCHAR **argv);
int _tmain(int argc, TCHAR *argv[]);

These are the _tmain function prototypes. The TCHAR macro translates either to char or to wchar_t. It is controlled by the UNICODE constatnt.

#define _UNICODE
#define UNICODE

#include <windows.h>
#include <tchar.h>

int _tmain(int argc, TCHAR *argv[]) 
{
    PDWORD cChars = NULL;
    HANDLE std = GetStdHandle(STD_OUTPUT_HANDLE);

    if (std == INVALID_HANDLE_VALUE) {
        _tprintf(L"Cannot retrieve standard output handle
 (%d)", 
            GetLastError());
    }  
        
    WriteConsole(std, argv[1], _tcslen(argv[1]), cChars, NULL);

    return EXIT_SUCCESS;
}

To compile this example, we need to have Microsoft extensions enabled. To enable Microsoft extensions, go to Project, Project options..., Compiler tab. In the Options part, click on the Enable Microsoft extensions check box.

#define _UNICODE
#define UNICODE

Here we define two constants. These definitions mean, that we are going to build unicode program. They translate C macros in C runtime and Windows header files. The _UNICODE constant translates macros in the C runtime. (These macros start with an underscore.) The UNICODE constant translates macros in the Windows header files.

#include <windows.h>

In this header file we have the definition of the TCHAR macro. It is affected by the UNICODE constant.

#include <tchar.h>

We must include this header file for the _tmain and _tcslen macros. They are translated depending on the _UNICODE macro.

int _tmain(int argc, TCHAR *argv[]) {

The _tmain() function translates in our case to wmain() and the TCHAR to wchar_t.

WriteConsole(std, argv[1], _tcslen(argv[1]), cChars, NULL);

The WriteConsole() function prints output to the console. The function is transleted to WriteConsoleW(). The _tcslen macro is translated to wcslen() function.

C:winapiexamples2systemMain3>Main3.exe "операционная система"
операционная система

The program takes another russian word (operating system) as a parameter and prints it to the console.

The WinMain function prototypes

So far we had console main functions. For graphical user interface development, we have to use one of the WinMain function prototypes.

int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, 
    PWSTR pCmdLine, int nCmdShow);
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, 
    LPSTR lpCmdLine, int nCmdShow);
int APIENTRY _tWinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, 
    LPTSTR lpCmdLine, int nCmdShow);

These three function prototypes are used for entry points for Windows GUI applications. ThewWinMain() function pCmdLine parameter contains the command-line arguments as a Unicode string. The WinMain() function pCmdLine parameter contains the command-line arguments as an ANSI string. The _tWinMain is a C macro that translates to other two function prototypes, depending whether the _UNICODE constant is defined or not.

When the entry point is WinMain(), the execution of the program begins in WinMainCRTStartup(). In case of wWinMain(), the execution begins in wWinMainCRTStartup().

#include <windows.h>

int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, 
               PWSTR szCmdLine, int CmdShow)
{
    MessageBoxW(NULL, szCmdLine, L"Title", MB_OK);

    return EXIT_SUCCESS;
}

This code shows a small message box on the screen. It shows the first command line argument. The argument can be supplied on the command line, or in the Project options on the General tab. There is an edit box called Command line arguments, where we can supply our command line arguments too.

int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, 
               PWSTR szCmdLine, int CmdShow)

The third parameter of the wWinMain() function is a PWSTR (pointer to wide string). It accepts wide characters.

Figure: A message box

In this part of the Winapi tutorial, we have mentioned main functions.