******************************************************************************S
===============================================================================
Test Department presents WIN32 Assembly Tutorial Part 000	01.03.1999
===============================================================================
I am,like you,just a beginner in PC assembly,with Atari XL assembly background.
So, sorry for all possible mistakes. I do my best ...
Everything I know about PC Assembly is in this tutorial & the tutorials before.
I don't like proc and invoke statements, everything here is pure assembler !!!
-------------------------------------------------------------------------------
Muchas gracias and my best wishes flys to: Iczelion, _HaK_, _masta_
I learn most of this stuff from your tutorials ...
-------------------------------------------------------------------------------
This tutorials are written for MASM32 V2 package and will work well with it.
==> All files you need to start & more could be find in the World Wide Web <==
-------------------------------------------------------------------------------
     http://win32asm.cjb.net - http://cracking.tsx.org - http://fravia.org
-------------------------------------------------------------------------------
   You can also visit my homepage:  http://www.geocities.com/Paris/Cafe/8444
===============================================================================
*******************************************************************************

-------------------------------------------------------------------------------
==> What you need:
-------------------------------------------------------------------------------
    1. Basic knowledge of assembly language and operating systems.
       C64, Amiga, Atari ST, Apple, MSDos 6 or Atari XL (like me) is OK.
    2. An Intel 386, better 486, or greater computer with Windows 95.
    3. MASM32 V2 Package, then you have all you need and more to start !
    4. The API reference WIN32.HLP and the resource file reference RC.HLP.
    5. The Assembler Book, Addison-Wesley, Trutz Eyke Podschun - buy it.
    6. A debugger like W32DASM V8.90 or Softice 3.24 will be a usefull help.

-------------------------------------------------------------------------------
==> Helpfull notes about assembly language and Windows 95:
-------------------------------------------------------------------------------
1. The very best note is: imagine Win95 is NOT coded in ASM, it's in C
2. The main note is the use of predefined API functions (OS functions).
   In WIN32.HLP you find a list of API functions and parameters names.
   API names are case sensitive !
3. You must set the correct path to the include files in your ASM file.
   API functions resist in the *.lib files you include.
4. You must declare all API functions you want use in the ASM file.
   Look into *.inc file,not *.lib file where the function resist,for help.
   Example: MessageBoxA resist in USER32.LIB, declare is in USER32.INC !
5. API parameter must PUSHed to the stack before the function is called.
   Important: PUSH the last parameter first, then the second-last ...
   You can find default PARAMETER NAMES in the file WIN32.HLP.       
   Look for default PARAMETER VALUES into WINDOWS.INC (it's a text file).
6. API functions give you one or more return value mostly in EAX !
   In WIN32.HLP you find more information about the return values.
7. Some API functions needs a DATA STRUCTURE defined in the .DATA section.
   This structure is a parameter block used by the specified API function.
8. A basic mask for our assembler programs named TESTDEP0.ASM is included in
   this tutorial 000.
   Take a look inside and learn how it works to increase your knowledge.
9. If you want add a menu bar, icon, sound, bitmap graphic etc. to your
   program you must create a resource file and link it with the asm file.
   A basic rc.file named RSRC.RC is included in this tutorial 000.
 
-------------------------------------------------------------------------------
==> The API function, an example:
-------------------------------------------------------------------------------
1. For example we create a Message Box with a YES and NO button.
   The API function call is "MessageBoxA"
2. Switch to our Api reference(WIN32.HLP),search for "MessageBox",and find:

   	int MessageBox
	(
       	HWND  hWnd,	   	// handle of owner window
       	LPCTSTR  lpText		// address of text in message box
       	LPCTSTR  lpCaption, 	// address of title of message box
       	UINT  uType 	   	// style of message box
	);

        "hWnd" if no window calls our MessageBox we set it to 0=no window
        "lpText" is a pointer to our textstring shown in the Message Box
        "lpCaption" is a pointer to our textstring shown in the titel bar
        "uType" is the type of the button in the Message Box

   So we look for possible parameter names in WIN32.HLP and choose
   MB_YESNO button.
   We can use this parameter name or, i prefer, the parameter value.
   For checking the parameter value of the parameter name MB_YESNO
   we search in WINDOWS.INC for the text MB_YESNO and find:
	MB_YESNO                             equ 4h
3. API functions gives you a return value (WIN32.HLP) mostly in EAX.
   It is up to you to react to this values, for example you can store it
   for later use.
4. Possible return values for our Message Box with uType MB_YESNO (4h)
   are stored in EAX, IDYES (6h) and IDNO (7h).
   Search in WINDOWS.INC for the text IDYES and for IDNO and find:
 	IDYES                                equ 6
	IDNO                                 equ 7
5. So our program looks like this:

	--- Declaration of the API function ---
	MessageBoxA		PROTO :DWORD, :DWORD, :DWORD, :DWORD

	--- Define the Text Strings for the Message Box ---
	.DATA
	MB1_Name 		db "Test Department",0	;message box name
	MB1_Text		db "Realy exit ?",0	;message box text

	--- This is the program code inside the CODE section ---
	.CODE
	push	4h		;uType, 4h=MB_YESNO Button
	push	OFFSET MB1_Name	;lpCaption, pointer to message box name
	push	OFFSET MB1_Text	;lpText, pointer to message box text
	push	0h		;hwnd, handle of owner window, 0=no owner
	call	MessageBoxA	;- API Function -
	cmp	eax,7h		;check if return value in EAX=7h (IDNO)

-------------------------------------------------------------------------------
==> The API function with a data structure, an example:
-------------------------------------------------------------------------------
1. In this example we use the API function "GetMessageA".
   This function retrieves a message and places it in the specified
   structure.
   For other API functions YOU (!) must fill the structure with the correct
   values before you call the API function.
   Do it very carefully; if one parameter is wrong the hole program crash.
2. Switch to our Api reference (WIN32.HLP), search for "GetMessageA" :

	BOOL GetMessage(
    	LPMSG  lpMsg,		// address of structure with message
    	HWND   hWnd,		// handle of window
    	UINT   wMsgFilterMin,	// first message
    	UINT   wMsgFilterMax 	// last message
   	);

3. You see this API functions needs a pointer to a structure where extra
   information were stored.
4. If an API function needs a data block structure you must create it in
   the DATA section.
5. So switch to the API reference (WIN32.HLP), search for MSG :

	typedef struct tagMSG {     // msg 
    	HWND   hwnd	;handle of the window whose window procedure receives
			;the message	 
    	UINT   message	;Specifies the message number 
    	WPARAM wParam	;Specifies additional information about the message
    	LPARAM lParam	;Specifies additional information about the message 
    	DWORD  time	;Specifies the time at which the message was posted 
    	POINT  pt	;Specifies the cursor position, in screen coordinates,
			;when the message was posted 
	} MSG		;
 
6. Well, our program looks like this:

	--- Define the structure MSG ---
	.DATA
	hwnd		dd 0h	;handle of window who receives message
	message		dd 0h	;the message number
	wParam		dd 0h	;extra info about the message
	lParam		dd 0h	;extra info about the message 
	time		dd 0h	;time the message was posted 
	pt		dd 0h	;cursor position message posted
	
	--- This is the program code inside the CODE section ---
	.CODE
	push	0h		;wMsgFilterMax, highest msg. value
	push	0h		;wMsgFilterMin, lowest msg. value
	push	0h		;hWnd, 0=get any message
	push	OFFSET hwnd	;lpMsg, push address of msg structure
	call	GetMessageA	;- API Function -
	cmp	eax,0FFFFFFFFh	;return value or error code (0FFFFFFFF) in EAX

-------------------------------------------------------------------------------
==> The resource file:
-------------------------------------------------------------------------------
A resource is a binary data that a resource compiler or developer adds to an
application's executable file.
A resource can be either standard or defined.
The data in a standard resource describes an icon, cursor, menu, dialog box,
bitmap, enhanced metafile, font, accelerator table, message-table entry,
string-table entry, or version.
An application-defined resource, also called a custom resource, contains any
data required by a specific application.
A basic rc.file named RSRC.RC is included in this tutorial 000.
Look in the resource help file (RC.HLP) for extra information !
------------------------------------------------------------------------------- 
Now look into the file rsrc.rc and let's go step by step:
-------------------------------------------------------------------------------
1. Define an icon, bitmap and sound you want use in the ASM file:

TDIcon		ICON	TDJolly.ico	;"TDIcon"=icon name
					;"ICON"=menu keyword
					;"TDJolly.ico"=filename of the icon
TDBitmap	BITMAP	TDPictur.bmp	;"TDBitmap"=bitmap name
					;"BITMAP"=menu keyword
					;"TDPictur.bmp"=filename of the bitmap
TDWave		WAVE	TDSound.wav	;"TDWave"=wave name
					;"WAVE"=menu keyword
					;"TDSound.wav"=filename of the wave
2. Here the menu description starts:

TDMenu  	MENU			;"TDMenu"=menu name,"MENU"=menu keyword
{					;"{"=start of menu, the same as "BEGIN"
MENUITEM 	"&Exit", 1		;"MENUITEM"=menu keyword
					;"&Exit"=MENUITEM Textstring
					;"&"=the next letter is underlined
					;"1"=the MENUITEM ID
MENUITEM 	"&Copy", 2		;"MENUITEM"=menu keyword
					;"&Copy"=MENUITEM Textstring
					;"&"=the next letter is the hot key
					;"2"=the MENUITEM ID
}					;"}"=end of MENU, the same as "END"

-------------------------------------------------------------------------------
==> Additional information about the resource file:
-------------------------------------------------------------------------------
1. MENUITEM statement doesn't invoke a popup menu when selected:

	MENUITEM "&Exit", ID [,options]

2. The ID is a number that identify the menu item in the message sent to
   the window procedure (lpfnWndProc) when the menu item is selected.
   You can use the option or combine them with "or" operator.
   INACTIVE and GRAYED cannot be combined together.
   Available options are:

	GRAYED 	  - The menu item is inactive, and it does not generate a
     		    WM_COMMAND message. The text is grayed.
	INACTIVE  - The menu item is inactive, and it does not generate a
     		    WM_COMMAND message. The text is displayed normally.
	MENUBREAK - This item and the following items appear on a new line of
     	   	    the menu.
	HELP  	  - This item and the following items are right-justified.

3. POPUP statement invokes a popup window when selected:

	POPUP "&Exit" [,options]
	{
	[menu list]
	}

4. SEPARATOR statement will draw a horizontal line in the popup window:

	POPUP "&Exit" [,options]
	{
	[menu item1]
	MENUITEM SEPARATOR
	[menu item2]
	}

5. If a menu item invokes a dialog box, you should append 3 epsilons
   (, , , 0) to the menu item string. 
6. The next step after you are finished with the menu resource script is
   to reference it in your program.
   If you declare your menu in the WNDCLASSEX Structure, API-function
   is RegisterClassEx, this menu becomes your default menu for every
   window you create from this class (0=no default menu):

	.DATA
	MenuName  db "TDMenu",0			;"TDMenu" your menu name

	.CODE
	mov	lpszMenuName,OFFSET MenuName	;pointer to menu name,0=no

7. If you load your menu and PUSH the handle into hMenu, before you call
   the API function CreateWindowClassEx, you can get individual menus
   for every window.

	.DATA
	MenuName  	db "TDMenu",0		;"TDMenu" your menu name
	hMenu	  	dd 0			;handle of your menu

	.CODE
	push 		OFFSET MenuName		;pointer to the menu name
	push		hInstance		;handle of your program
	call		LoadMenuA		;API function, loads menu
	mov		hMenu,eax		;get the menu ID
 	
8. When the user selects a menu item, the window procedure, defined in the
   API function RegisterClassEx, lpfnWndProc will receive a WM_COMMAND
   message.
   The low word of wParam contains the menu ID of the selected menu item.
   It's up to you to react to this parameter, in ax, in your lpfnWndProc
   routine.

*******************************************************************************
===============================================================================
Test Department presents WIN32 Assembly Tutorial Part 000	01.03.1999
===============================================================================
******************************************************************************E