Using MAPWIN
------------

MAPWIN, written by Richard Smith (president of Phar Lap
Software), is a program that makes it easy to see what API functions
a Windows program uses, or what functions a dynamic-link library
(DLL) or device driver provides. Phar Lap generally uses this
utility to determine what API functions need to be implemented in
order to run a program under its 286|DOS-Extender environment. You
can use it to snoop around inside Windows, and uncover useful
undocumented API functions.

MAPWIN is a character-mode program that runs under DOS, the DOS
box in Windows, or in OS/2 1.x.

To use MAPWIN, simply point it at a Windows executable file. The
output can be redirected to a file. For example:

C:\BIN>mapwin \windows\taskman.exe > taskman.log

C:\BIN>mapwin \windows\system\user.exe > user.log

C:\BIN>mapwin \windows\system\system.drv > system.log

MAPWIN will produce a list of the executable's exports, and
another list of its imports, plus some other information. For
example:

;-----------------------------------------------------------

C:\BIN>mapwin \windows\system\system.drv
MAPWIN: 4.0 -- Copyright (C) 1986-91 Phar Lap Software, Inc.

Dump of the .DLL file -- \windows\system\system.drv

Header information

Target operating system................Windows
Initial CS:IP..........................#0001:01F2
DLL initialization.....................One time
Automatic data segment.................None

DLLs called by this program

KERNEL

Exported entry points

WEP (system.10)
A20_PROC (system.20)
CREATESYSTEMTIMER (system.2)
INQUIRESYSTEM (system.1)
SAVE80X87STATE (system.8)
KILLSYSTEMTIMER (system.3)
GET80X87SAVESIZE (system.7)
GETSYSTEMMSECCOUNT (system.6)
RESTORE80X87STATE (system.9)
ENABLESYSTEMTIMERS (system.4)
DISABLESYSTEMTIMERS (system.5)

Imported references

__ROMBIOS (KERNEL.173)
ALLOCCSTODSALIAS (KERNEL.170)
NOHOOKDOSCALL (KERNEL.101)

;-----------------------------------------------------------

The imports are assigned names based on a table built into
MAPWIN.EXE, which matches module.ordinal pairs (such as KERNEL.101
above) with ASCII function names (such as NOHOOKDOSCALL above).

The table built into MAPWIN can be overriden. MAPWIN does not
"know" about all Windows 3.0 DLLs and device drivers; nor does it
know about vendor-specific DLLs that come with many Windows
applications; nor, of course, does it know about any new functions
provided by Windows 3.1. MAPWIN can be extended by specifying an
"import file" on the command line (you must give an exact path). For
example:

C:\BIN>mapwin @\pcmag\win30.imp \windows\taskman.exe

An import files contains one or more lines such as the following:

-IMPORT GETTABBEDTEXTEXTENT=USER.197
-IMPORT CASCADECHILDWINDOWS=USER.198
-IMPORT TILECHILDWINDOWS=USER.199
-IMPORT OPENCOMM=USER.200

MAPWIN.ZIP comes with the file WIN30.IMP, which includes all
exports from COMM.DRV, GDI.EXE, KRNL386.EXE (KERNEL module),
KEYBOARD.DRV, LZEXPAND.DLL, MOUSE.DRV, SOUND.DRV, SYSTEM.DRV,
USER.EXE, VGA.DRV (DISPLAY module), WINDEBUG.DLL, and WINMEM32.DLL.
In addition, undocumented API functions are marked with @@ to make
them stand out and to make it easy for you to search for them, using
a tool such as grep or DOS sort. Obscure (but documented somewhere!)
functions are marked with @; finally, the GetProcAddress() function
is marked with $$ to remind you that, if a program calls this
run-time dynamic linking function, then static examination of the
file probably won't reveal all the API functions that it uses. Using
WIN30.IMP, MAPWIN output will look something like this:

Imported reference(s)

ARRANGEICONICWINDOWS (USER.170)
CASCADECHILDWINDOWS@@ (USER.198)
DIALOGBOX (USER.87)
GETDESKTOPHWND@ (USER.278)
GETDLGITEM (USER.91)
GETPROCADDRESS$$ (KERNEL.50)
GETSYSTEMMETRICS (USER.179)
GETTASKFROMHWND@ (USER.117)
INITAPP@ (USER.5)
INITTASK@ (KERNEL.91)
ISWINOLDAPTASK@@ (KERNEL.158)
SWITCHTOTHISWINDOW@@ (USER.172)
TILECHILDWINDOWS@@ (USER.199)
UNLOCKSEGMENT (KERNEL.24)
WAITEVENT@ (KERNEL.30)

Here, functions such as CascadeChildWindows() and
IsWinOldApTask() are marked with @@ because they are undocumented.
The functions GetDesktopHwnd() and GetTaskFromHwnd() are given only a
single @ because, while undocumented, they are identical to
documented functions (GetDesktopWindow() and GetWindowTask()) and are
therefore uninteresting. Functions such as InitApp() and InitTask()
are also given a single @ because, while not listed in WINDOWS.H or
in the Microsoft Windows _Programmer's Reference_, they _have_ been
documented by Microsoft as part of "Open Tools".

To find all undocumented functions (assuming you have egrep from
one of the collections of Unix-compatible tools such as the MKS
Toolkit or the Thompson Toolkit):

C:\BIN>egrep @@ win30.imp

To find all quasi-documented functions:

C:\BIN>egrep [^@]@ win30.imp

If you don't have grep, egrep, or fgrep, you can always use
FIND from DOS:

C:\BIN>\dos\find "@" win30.imp

For the statistics collectors among you, it might be interesting
to note that 934 Windows 3.0 functions are listed in WIN30.IMP, of
which 248 are designated as undocumented, and an additional 88 are
designated as quasi-documented.

In addition to WIN30.IMP, you can create your own *.IMP files by
using the MAPWIN -IMPMAKE switch. When Windows 3.1 becomes
available, for instance, you can produce a WIN31.IMP file by running
MAPWIN -IMPMAKE on all its EXEs, DLLs, DRVs, and so on (make sure you
don't miss any!):

C:\BIN>for %f in (\win31\system\*.exe) do mapwin -impmake %f >> win31.imp

C:\BIN>for %f in (\win31\system\*.dll) do mapwin -impmake %f >> win31.imp

C:\BIN>for %f in (\win31\system\*.drv) do mapwin -impmake %f >> win31.imp

Naturally, you can produce additional *.IMP files for the vendor-
specific DLLs provided with any applications you use, for Windows
Multimedia, Pen Windows, and so on.

You can specify multiple *.IMP files on the MAPWIN command line,
like so:

C:\BIN>mapwin @win30.imp @phoo.imp @bar.imp \baz\zar\quux.exe

Once you have run MAPWIN on a program, you may want a quick way
to see what undocumented or quasi-documented calls it's making. Just
use the DOS pipe | to put MAPWIN together with GREP or FIND:

C:\BIN>mapwin @\pcmag\win30.imp \phoo\bar\someprog.exe | \dos\find "@@"

MAPWIN is extracted from a far more extensive Phar Lap utility.

-- Andrew Schulman
CIS 76320,302
Internet: [email protected]