Win32 Programming: How to create a simple Console based application?

Microsoft Windows’s Win32 API (Application Programming Interface) is for developing applications on 32-bit Windows platforms. Win32 also introduced API functions for 64-bit applications. So, using Win32 API we can develop both 32-bit and 64-bit applications.

Programming using Win32 API is bit difficult compare to programming using MFC (Microsoft Foundation Classes). MFC is a framework mostly wraps on Win32 API. Win32 API functions are pure “C” functions; hence no object oriented concepts used. MFC framework is developed based on object oriented concepts; CObject class is the base class for most of the MFC classes.

In this article I am going to explain the steps to develop a simple Win32 console based application using Visual C++.

Generally Win32 based applications have a WinMain function. Like main() function is an entry point for “C” and “C++” applications, WinMain function is an entry point for Win32 based applications. The syntax of the WinMain function is looks like below:

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpszCmdline, int nCmdShow);

Where hInstance is the application handle. hPrevInstance is a handle to the previous instance of the application. lpszCmdline is the command line arguments string (excluding the application name). nCmdShow tells how to show the Win32 window; hides the window (SW_HIDE), minimize the window (SW_MINIMIZE), maximize the window (SW_MAXIMIZE) etc.,.

Lets write a simple program to display “Hello, World!” on the screen. Below is the code.

// sample.c
#include <windows.h>

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpszCmdline, int nCmdShow)
{
	printf("Hello, World!");

	return 0;
}

Compile the program using below command at command prompt:

cl sample.c

Observe that the above code is successfully compiled and Visual C++ compiler generates a “sample.exe” file. We are expecting to display “Hello, World!” text when we run this program. Lets run this; we found that nothing is displayed on the console window.

The reason behind this is, there will be no console window attached to the application. Remember that this is a Win32 based application; not the normal “C” application. But we can use main() function as an entry point instead of WinMain function. When we use main() function as an entry point, the above code will work fine and display “Hello, World!” message on the console window; because the console window will be available. When we use WinMain function as an entry point, no console window will be attached to the application; hence no message is displayed. So, we need to create a console window and display some text on it using console related functions.

Console functions are used to read from or write to the console. We are going to use AllocConsole, FreeConsole, WriteConsole and GetStdHandle Console functions in our program. So, lets discuss about these console functions first:

AllocConsole Win32 API function is used to allocate a console for the calling process and returns a non-zero value upon success. Each process can be associated with a single console. If already a console is attached to the calling process, AllocConsole function call will fail.

To detach a console from the process we use FreeConsole Win32 API function. Upon success, this function will return a non-zero value.

Once the console is attached to process, we can use console functions to write to the console. WriteConsole Win32 API function is used for this purpose. The syntax of this function is like below:

BOOL WINAPI WriteConsole(HANDLE hConsoleOutput, 
			   const VOID *lpBuffer, 
			   DWORD nNumberOfCharsToWrite, 
			   LPDWORD lpNumberOfCharsWritten, 
			   LPVOID lpReserved);

Where hConsoleOutput is the handle to the console screen buffer. lpBuffer is a pointer to the buffer that contains the text to write to the console. nNumberOfCharsToWrite is the total number of characters to write to the console. lpNumberOfCharsWritten is the address of the variable that receives the number of characters actually written. lpReserved is the reserved argument and the value must be NULL. Upon success this function returns a non-zero value.

As discussed above, the first argument in WriteConsole Win32 API function is a handle to the console screen buffer. But how do we get this handle? We have to use another Win32 API function; GetStdHandle to retrieve the handle to the console screen buffer (standard output device). GetStdHandle takes a singe argument and returns the valid handle, upon success.

All together below is the code:

// sample.c
#include <windows.h>

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpszCmdline, int nCmdShow)
/* We can also use main() as an entry function. */
//int main()
{
	char text[] = "Hello, World!";

	if ( WriteConsole(GetStdHandle(STD_OUTPUT_HANDLE), text, strlen(text), NULL, NULL) == FALSE )
	{
		if ( AllocConsole() == TRUE )
		{
			WriteConsole(GetStdHandle(STD_OUTPUT_HANDLE), text, strlen(text), NULL, NULL);

			getch();

			FreeConsole();
		}
	}
       else
               getch();
	return 0;
}

Above code will display a “Hello, World!” message on console window.

We have successfully created a Win32 console application and display the “Hello, World!” message on console window.

We all know, it is comfortable to use a printf statement while debugging a console application. For Win32 based console applications we can use OutputDebugString function to display the string in Output window or in an attached Debugger.

**

Leave a Reply