You are currently offline, waiting for your internet to reconnect

How To Call 16-bit Code from 32-bit Code Under Windows 95, Windows 98, and Windows Me

This article was previously published under Q155763
SUMMARY
As a developer, you may need to access the functionality provided by a 16-bit dynamic-link library (DLL) from your Win32 application. This is trueparticularly when you do not have the source code for the DLL so that youcan port it to Win32. This article discusses the mechanism by which 32-bitDLLs can call 16-bit DLLs. The mechanism is called a thunk and the methodimplemented under Microsoft Windows 95, Windows 98, and Windows Millennium Edition is called a flat thunk.

The following describes the three major steps involved in creating a flatthunk:
  1. Create the thunk script.
  2. Build the 32-bit DLL.
  3. Build the 16-bit DLL.
MORE INFORMATION
A flat thunk consists of a 32-bit and a 16-bit DLL that work together.A Win32 application calls the 32-bit DLL, and the 32-bit DLL calls anexported function in the 16-bit DLL. When the function in the 16-bitDLL returns, it returns back to the 32-bit DLL, which in turn returnsback to the Win32 application. The 32-bit and 16-bit DLLs work bycalling the Windows 95 32-bit and 16-bit kernels to handle all of thelow-level details necessary to make the transition from 32-bit to16-bit code and back.

Designing a new flat thunk involves creating a thunk script (.thk file).This script is compiled with the Thunk compiler into an assembly-language file, which is then assembled twice; one time with each of twoflags of -DIS_32 and -DIS_16. This allows you to create both the 32-bitand 16-bit object modules. These object modules are linked in the 32-bitand 16-bit DLLs, respectively. The following diagram summarizes thefiles involved in building the DLLs:
                         +------------+                         | 32to16.thk |                         +------------+                               |                         +------------+                         | 32to16.asm |                         +------------+                           /         \                   -DIS_32 /           \ -DIS_16                        /              \                   +-----------+  +-----------+                  | 32THK.obj |  | 16THK.obj |                  +-----------+  +-----------+                        /                 \         +-------+    +-------+             +-------+        | APP32 | -> | DLL32 | -- THUNK -- | DLL16 |        +-------+    +-------+             +-------+				

Tools Needed to Build Flat Thunks

  • Microsoft Visual C++ version 1.5x (16-bit) compiler for the 16-bit side of creating the thunk. The 16-bit side of the thunk is a 16-bit DLL.
  • Microsoft Visual C++ version 2.x or higher (32-bit) compiler for creating the 32-bit side of the thunk. The 32-bit side of the thunk is a 32-bit DLL.
  • Thunk compiler (Thunk.exe) from the Microsoft Win32 SDK for compiling thunk scripts.
  • Microsoft Macro Assembler (MASM) version 6.1 or higher for assembling the assembly-language output of the thunk compiler.
  • 16-bit Rc.exe file from the BINW16 directory of the Microsoft Win32 SDK for marking the 16-bit thunk DLL as version 4.0.

Creating the Thunk Script

You need to create a script that can be used by the Thunk compiler tocreate a thunk. A thunk script is a text file that contains typedefinitions, the function prototypes of the functions you wish to call viathunks and a specification of the direction of the parameters for eachfunction. For example, some functions require both input and outputparameters while others may only require input parameters. Thunk scriptsuse special syntax to describe whether parameters are input, output, orboth input and output.

A thunk script for 32->16 thunks begins with the following statement:
enablemapdirect3216 = true;
The Thunk compiler expects that the 32-bit side of the thunk is declaredas __stdcall, and that the 16-bit side is __far __pascal. (The WINAPIdeclaration takes care of this on both sides.) The __cdecl and__fastcall calling conventions are not supported by the Thunk compiler.Note, however, that the Thunk compiler does not actually accept the__far, __pascal, or __stdcall keywords; they are assumed.

The following example shows a thunk script for a function that has noparameters:
   enablemapdirect3216 = true;   void MyThunk16()   {   }				
The equivalent declaration would be:
   C   language:  void WINAPI MyThunk16(void);   C++ language:  extern "C" void WINAPI MyThunk16();				
The following example script describes a function that takes twoparameters and returns a value. The second parameter is an outputparameter that contains a pointer that is passed back to the 32-bit DLL.
   enablemapdirect3216 = true;   typedef int   BOOL;   typedef char *LPSTR;   BOOL MyThunk16(LPSTR lpstrInput, LPSTR lpstrOutput)   {      lpstrInput  = input;    // optional; input is default      lpstrOutput = output;   }				
The statement "lpstrOutput = output" tells the Thunk compiler that the16-bit function returns an address that needs to be converted froma selector:offset pointer into a 32-bit linear address.

The following thunk script uses more complex parameter types such asstructures. This example also shows how to specify input and outputparameters.
   enablemapdirect1632 = true;   typedef unsigned int UINT;   typedef char *LPSTR;   typedef struct _POINT {      UINT x;      UINT y;   }POINT, *LPPOINT;   typedef struct _CIRCLE {      POINT center;      UINT  radius;   }CIRCLE, *LPCIRCLE;   void MyThunk32( LPCIRCLE lpCircleInOut)   {      lpCircleInOut = inout;   }				
The statement "lpCircleInOut = inout" tells the script compiler thatthis pointer is going to be used for input and output. This causes theThunk compiler to convert lpCircleInOut from a 32-bit linear addressto a selector:offset pointer when the function is called and then backto a 32-bit linear address when the function returns. The conversionis handled by the thunk created by the Thunk compiler.

Using the Thunk Compiler

The Thunk compiler usage is as follows:
thunk.exe /options <inputfile> -o <outputfile>
The following command line shows how to compile a 32->16 thunk script.This line takes a thunk script named 32to16.thk and produces anassembly-language file named 32to16.asm.
thunk -t thk 32to16.thk -o 32to16.asm
The "-t thk" option tells the Thunk compiler to prefix the thunkfunctions in the assembly-language file with "thk_." This prefix isused when linking multiple thunk scripts into a pair of DLLs, and isuseful for creating a pair of DLLs that contain both 32->16 and16->32 thunks. Each thunk script should have a unique prefix.

Building the 32-bit DLL

  1. In the DllMain function of your 32-bit DLL, you must make a call to a function created by the Thunk compiler named thk_ThunkConnect32 for every reason (dwReason) DllMain is called, as shown here ("thk" is the prefix from the Thunk compiler -t switch):
          // prototype for function in .obj file from the thunk script      BOOL WINAPI thk_ThunkConnect32(LPSTR     lpDll16,                                     LPSTR     lpDll32,                                     HINSTANCE hDllInst,                                     DWORD     dwReason);      BOOL WINAPI DllMain(HINSTANCE hDLLInst,                          DWORD     dwReason,                          LPVOID    lpvReserved)      {         if (!thk_ThunkConnect32("DLL16.DLL", "DLL32.DLL",                                 hDLLInst, dwReason))         {            return FALSE;         }         switch (dwReason)         {            case DLL_PROCESS_ATTACH:               break;            case DLL_PROCESS_DETACH:               break;            case DLL_THREAD_ATTACH:               break;            case DLL_THREAD_DETACH:               break;         }         return TRUE;      }						
  2. Include the following lines in the EXPORTS section of the module definition (.def ) file for the 32-bit DLL. For example:
             thk_ThunkData32						
  3. Export the functions that the Win32 application calls. You can either use the 32-bit DLL's module definition (.def) file or the __declspec(dllexport) keyword. Be sure the functions are declared and defined as __stdcall (or WINAPI). If the 32-bit DLL is written in C++, be sure to declare the functions as extern "C" as well.
  4. Compile the thunk script as follows (if not already compiled):
          thunk -t thk 32to16.thk -o 32to16.asm						
  5. Assemble the assembly-language file produced by the Thunk compiler as a 32-bit object module. For example:
          ml /DIS_32 /c /W3 /nologo /coff /Fo thk32.obj 32to16.asm						
  6. Link this object module as part of the 32-bit DLL.
  7. Link the Thunk32.lib library as part of the 32-bit DLL. This is the 32-bit import library provided in the Win32 SDK that contains references to the 32-bit thunking APIs that the code created by the Thunk compiler uses.

Building the 16-bit DLL

  1. The 16-bit DLL must export a function named "DllEntryPoint." This function must make a call to a function created by the Thunk compiler named thk__ThunkConnect16 ("thk" is the prefix from the Thunk compiler -t switch) every time DllEntryPoint is called:
          // prototype for function in .obj file from the thunk script      BOOL WINAPI __export thk_ThunkConnect16(LPSTR lpDll16,                                              LPSTR lpDll32,                                              WORD  hInst,                                              DWORD dwReason);      BOOL WINAPI __export DllEntryPoint(DWORD dwReason,                                         WORD  hInst,                                         WORD  wDS,                                         WORD  wHeapSize,                                         DWORD dwReserved1,                                         WORD  wReserved 2)      {         if (!thk_ThunkConnect16("DLL16.DLL",                                 "DLL32.DLL",                                 hInst,                                 dwReason))         {            return FALSE;         }         return TRUE;      }						
  2. Include the following lines in the IMPORTS section of the module definition (.def) file for the 16-bit DLL. For example:
          C16ThkSL01      = KERNEL.631      ThunkConnect16  = KERNEL.651						
  3. Include the following lines in the EXPORTS section of the module definition (.def) file for the 16-bit DLL. THK_THUNKDATA16 is defined in the object file that is assembled from the output of the Thunk compiler. Both of these symbols must have the RESIDENTNAME keyword, but can have any ordinal number.
          THK_THUNKDATA16 @1  RESIDENTNAME      DllEntryPoint   @2  RESIDENTNAME						
  4. Add the thunk functions to the EXPORTS statement of the 16-bit DLL's module definition (.def) file. Be sure they are declared and defined as__far __pascal __export (or WINAPI __export). If the DLL is written in C++, be sure to declare them as extern "C" as well. The 32-bit side of the thunk calls these functions.
  5. Compile the thunk script as follows (if not already compiled):
          thunk -t thk 32to16.thk -o 32to16.asm						
  6. Assemble the assembly-language file produced by the Thunk compiler as a 16-bit object module. For example:
          ml /DIS_16 /c /W3 /nologo /Fo thk16.obj 32to16.asm						
  7. Link this object module as part of the 16-bit DLL.
  8. Mark the 16-bit DLL as version 4.0. To do this, use the resource compiler (Rc.exe). The following line shows the syntax:
    rc -40 <DLL file>
    This -40 option is available in the Resource Compiler that is provided with the Win32 SDK.

    NOTE: Be sure to use the Rc.exe file in the BINW16 directory so that the DLL is marked with version 4.0. The Rc.exe file that ships with 16-bit versions of Microsoft Visual C++ does not mark the DLL as version 4.0.
REFERENCES
For information about how to debug flat thunks, please refer to thefollowing article in the Microsoft Knowledge Base:
133722 How To Debug Flat Thunks
win95 flat thunk win16 debug
Properties

Article ID: 155763 - Last Review: 07/11/2005 20:18:00 - Revision: 2.3

  • Microsoft Win32 Application Programming Interface
  • kbhowto kbtshoot kbapi kbnetwork kbprogramming kbkernbase kbthunks KB155763
Feedback