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

Microsoft Windows’s Win32 API (Application Programming Interface) is mainly for developing applications on 32-bit Windows platforms. As we have 64-bit systems, 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 a bit difficult compared to programming using MFC (Microsoft Foundation Classes). MFC is a framework that mostly wraps on Win32 API. Win32 API functions are pure “C” functions; hence no object-oriented concepts are 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, we are going to discuss the steps needed to develop a simple Win32 console-based application using Visual C++.

Generally, Win32-based applications have a WinMain function. Like the main() function is an entry point for “C” and “C++” applications, The WinMain function is an entry point for Win32-based applications. The syntax of the WinMain function looks like the 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.

Let’s 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 the below command at the command prompt:

cl sample.c

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

The reason behind this is, that there is no console window attached to the application. Remember that this is a Win32-based application; not the normal “C” application. But we can use the main() function as an entry point instead of the WinMain function. When we use the main() function as an entry point, the above code will work fine and display the “Hello, World!” message on the console window. When we use the WinMain function as an entry point, no console window will be attached to the application; hence no message is displayed when we use the printf() function to display the messages.

As we do not have the console window already attached to the Win32 application, we need to first create a console window and display some text in it using console-related functions. Lets’ see how this can be achieved.

Console functions are used to read from or write to the console. We are going to use AllocConsole, FreeConsole, and WriteConsole console functions in our program. So, let’s discuss these console functions first.

Allocate a console using AllocConsole function

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, the AllocConsole function call will fail.

Detach a console from the application

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

Write to the console using WriteConsole function

Once the console is attached to the process, we can use console functions to write to the console. The 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 the 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 single argument and returns the valid handle, upon success.

Working example

Let’s put it all together and below is the working code:

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

#pragma comment(lib,"user32.lib")

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 ( AllocConsole() == TRUE )
	{
		WriteConsole(GetStdHandle(STD_OUTPUT_HANDLE), text, strlen(text), NULL, NULL);

		MessageBox(NULL, "Success", "Message", MB_OK);

		FreeConsole();
	}

	return 0;
}

The above code will display a “Hello, World!” message on the console window.

We have successfully created a Win32 console application and displayed the “Hello, World!” message on the 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.

**