Using resource files in your masm projects

In a previous post we built a boilerplate program that we can start to work with. For today’s post, we’re going to go through the development of a resource file that you can incorporate into your own projects.

What are resource files?

You can use resource files to organise your external resources (images, audio, text, etc.) into a compilable (and ultimately linkable) resource. The items that you add to your resource file are then statically added to your resulting executable, ready for you to reference.

From the Microsoft site:

You should place every element of the user interface that needs to be localized in a Windows resource file, including pictures, strings, messages, menus, dialog boxes, and version information. The table below lists the individual resource elements defined by Windows.

What does a resource file look like?

The .RC file itself is just text. There are IDs that are defined throughout that you can create symbolic constants for in your code, just so you’re not doing so much “magic number” work. Here’s a simple menu:

600 MENUEX MOVEABLE IMPURE LOADONCALL DISCARDABLE
BEGIN
    POPUP "&File", , , 0
    BEGIN
        MENUITEM "&Exit", 1000
    END
    POPUP "&Help", , , 0
    BEGIN
        MENUITEM "&About", 1900
    END
END

600 in this example is the ID of the menu. Referencing this menu in your code is as simple as passing 600 to the menu name parameter of a LoadMenu call:

invoke LoadMenu, hInstance, 600
invoke SetMenu, hWnd, eax

How do I compile one?

rc.exe is the resource compiler that comes along with masm32. You give it your resource script and it’ll give you back a compiled .RES file.

rc /v rsrc.rc

You then take the .RES file that was output; in this case it was rsrc.res and feed it into another utility cvtres.exe.

cvtres /machine:ix86 rsrc.res

This utility converts your compiled .RES file into object code. It produces you an .OBJ file that you can then link into your exe.

Windows programs with masm32

In a previous post I wrote about the basics of getting a program written and compiled using masm32 for the windows platform. In today’s post, I’m going to walkthrough the basic anatomy of a windows program that play the key roles in your application.

This information is language agnostic. It’s standard windows programming knowledge that I’ll present in the form of assembly programming with masm32. By the end of this blog post, you’ll have a good starting point (in boilerplate code) for any program that you want to write with masm32.

The basic pieces

In any windows program (using the Win32 API) there are some basic pieces that you’ll see most of the time.

• Main entry point (WinMain)
• Window creation
• Window handler procedure (WNDPROC)
• Message pump

These basic building blocks that you’ll see in just about all windows applications.

WinMain

This is your application’s main entry point. It’s analogous to the main function that you use when writing applicatioons in C/C++. From Microsoft’s site:

The user-provided entry point for a graphical Windows-based application.

Its function signature takes the following form:

int CALLBACK WinMain(
  _In_ HINSTANCE hInstance,
  _In_ HINSTANCE hPrevInstance,
  _In_ LPSTR     lpCmdLine,
  _In_ int       nCmdShow
);

This definition needs to be translated from C into assembly language. The HINSTANCE, LPSTR and int data types all reduce down to DWORD easily, so:

WinMain proc 	hInst 		:dword, 
				hPrevInst 	:dword,
				szCmdLine 	:dword,
				nShowCmd 	:dword

Being at the assembly layer, we’re exposed a little earlier in the process than what WinMain affords us, so we have extra work to do in terms of getting our application running. We as the implementers of the program need to invoke WinMain directly as this is not done for us.

invoke 	GetModuleHandle, NULL
mov		hInstance, eax

invoke	GetCommandLine
mov		lpszCmdLine, eax

invoke 	WinMain, hInstance, NULL, lpszCmdLine, SW_SHOWDEFAULT
invoke	ExitProcess, eax

GetModuleHandle allows us to fill the hInstance parameter and GetCommandLine gives us lpszCmdLine. hPrevInstance, according to the documentation is always NULL and nShowCmd is an SW_ series value that controls how our main application window is shown.

Window creation

The creation of a window is broken down into a few smaller steps:

• Register a window class
• Create the window
• Show the window

Registering a window class is just filling out the WNDCLASSEX structure and calling RegisterClassEx. Registering a windows class establishes base or common attributes about a window that you can re-use in subsequent calls to CreateWindow.

local 	wc 		:WNDCLASSEX
local 	msg 	:MSG
local 	hWnd 	:HWND

szText	szClassName, "BasicWindow"
szText	szWindowTitle, "First Window"

mov		wc.cbSize, sizeof WNDCLASSEX
mov		wc.style, CS_HREDRAW or CS_VREDRAW or CS_BYTEALIGNWINDOW
mov 	wc.lpfnWndProc, WndProc
mov 	wc.cbClsExtra, NULL
mov		wc.cbWndExtra, NULL

push	hInst
pop 	wc.hInstance

mov		wc.hbrBackground, COLOR_BTNFACE + 1
mov		wc.lpszMenuName, NULL
mov 	wc.lpszClassName, offset szClassName

invoke	LoadIcon, hInst, IDI_APPLICATION
mov		wc.hIcon, eax
mov		wc.hIconSm, eax

invoke	LoadCursor, hInst, IDC_ARROW
mov		wc.hCursor, eax

invoke	RegisterClassEx, addr wc

The macro szText is setup to allow you to ad-hoc define string variables where ever you need to. The rest of this is mainly filling out the structure and finally registering it. Setting lpfnWndProc has special significance to us here as we’ll go on to describe WNDPROC and its role in the application.

WindowProc callback function

When an application receives messages from the operating system, it handles this information through the window procedure. The window procedure interface is defined as:

LRESULT CALLBACK WindowProc(
  _In_ HWND   hwnd,
  _In_ UINT   uMsg,
  _In_ WPARAM wParam,
  _In_ LPARAM lParam
);

Again, translating this into assembly:

WndProc proc 	hWin 	:dword,
				uMsg 	:dword,
				wParam 	:dword,
				lParam 	:dword

The message pump

Finally, the thing that’s keeping our application alive is the message pump. It’s a loop of GetMessage, TranslateMessage and DispatchMessage.

MessagePump:

	invoke 	GetMessage, addr msg, NULL, 0, 0

	cmp 	eax, 0
	je 		MessagePumpEnd

	invoke	TranslateMessage, addr msg
	invoke	DispatchMessage, addr msg

	jmp 	MessagePump

MessagePumpEnd:

All together now

The following gist is all of the pieces assembled in a basic application that’s runnable (once assembled and linked).

Windows Development with NASM

In this post, I’ll walk through the steps required to bootstrap your development experience against the Win32 API using the Netwide Assembler.

Prerequisites

Before starting, you’ll need some software. I’ve used the following software set, however you can use any linker and resource compiler that you like.

• Nasm
• ALink
• Gorc
• Win32 include file

You’ll use Nasm to reduce your assembly source code into COFF object files. Gorc will take your resource scripts and produce linkable object files from these. Finally, ALink will bind all of your object files into a windows executable.

Finally, you’re going to need a copy of the include file for the Win32 API. The API itself is huge; the number of constants and structures is mind boggling. The link above handles all of these for you.

Test program

Probably the easiest thing to accomplish, is showing a message box. You need to show the message box and then return control back to Windows. You do this with calls to MessageBoxA and ExitProcess. The “A” in MessageBoxA as we’re not dealing with the wide-char version of these functions.

Here’s the code.

%include "win32n.inc"

extern MessageBoxA
import MessageBoxA user32.dll

extern ExitProcess
import ExitProcess kernel32.dll

segment .data USE32

	title	db "A message for you", 0
	message db "This is your first message", 0

segment	.bss USE32

segment .code USE32

..start:

	; show the message box
	push MB_OK
	push title
	push message
	push 0
	call [MessageBoxA]

	; return control back to windows
	push 0
	call [ExitProcess]

Functions are imported from the api using import, and are called in a very assembler-traditional fashion here. Taking a look at the definition for the MessageBox function, we can see the order of parameters:

int WINAPI MessageBox(
  HWND    hWnd,
  LPCTSTR lpText,
  LPCTSTR lpCaption,
  UINT    uType
);

Arguments are pushed to the stack in reverse order.

Assembling and linking

Now that you’ve got your source file, hello.asm you can produce an object file with the following:

C:\src> nasm -i c:\nasm\include -f obj hello.asm

You can now link the object file into an executable with the following:

C:\src> alink -c -oPE -subsys gui hello

Ready to go.

Making things a little more high-level

You can make your assembly code a little more high-level by using the nagoa+.inc include file. This include file provides your programs with some really handy constructs (as well as the win32 api bindings), so function invocations now look like this:

call MessageBoxA, 0, message, title, MB_OK
call ExitProcess, 0

Conclusion

This will get you started at least with Nasm in Windows development. Here is a great resource, full of links on assembly development.

Windows Development with MASM

In this post, I’ll walk through the steps required to bootstrap your development experience against the Win32 API using the Microsoft’s Macro Assember.

Prerequisites

Downloading the package from the masm32.com site will be everything that you need to produce applications using assembly language. It not only includes the assember ml, but also includes all of the library, include files and linker for you.

Test program

Here’s the code to present a message box.

; #######################

  .386
  .model flat, stdcall
  option casemap :none   ; case sensitive

; #######################

  include windows.inc
  include user32.inc
  include kernel32.inc

  includelib user32.lib
  includelib kernel32.lib

; #######################

.data

  szTitle  db "Your message", 0
  szMsg    db "First message box", 0

.code

start:

  invoke MessageBox, 0, offset szMsg, offset szTitle, MB_OK
  invoke ExitProcess, 0

end start

invoke goes a long way to cleaning up how any assembly program that is sub-routine heavy looks. The include files already do the externing of library symbols so that your code doesn’t need to explicitly declare that you’re using a particular function.

Assembling and linking

Now that you’ve got your source file, hello.asm you can produce an object file and executable with the following:

C:\src> ml.exe /IC:\masm32\include /coff hello.asm /link /SUBSYSTEM:WINDOWS /LIBPATH:C:\masm32\lib

You can see that not only assembler switches are passed, but also linker switches which means you’re assembling and linking all in one step.

Conclusion

The bundle for masm32 that this article refers to is great in the amount of code that it offers you, but the provided assembler is well-dated. Microsoft have been keeping masm updated from their website with 64 bit versions available with their development tools.

Windows Development with FASM

In this post, I’ll walk through the steps required to bootstrap your development experience against the Win32 API using the Flat Assembler.

Prerequisites

Everything is provided for you when you download the fasmw package, including libraries, include files. fasmw even includes a linker pre-geared for windows as your target.

Test program

Here’s the code to present a message box.

include 'win32ax.inc'

.code

	start:

		invoke MessageBox, HWND_DESKTOP, 'This is a test', 'Hey, Hey!', MB_OK
		invoke ExitProcess, 0

.end start

Everything is provided to you through win32ax.inc. This can be swapped out easily enough with a 64 bit counterpart if you’re targeting different architectures.

Assembling and linking

Now that you’ve got your source file, hello.asm you can produce an object file with the following:

C:\src> fasm hello.asm

That’s all there is to it. You’ll now have an exe available to you to run. The only gotcha is giving fasm a hint as to where your include files are, and you do this through the INCLUDE environment variable:

SET INCLUDE=C:\fasmw\include