ID: Q155763
- Microsoft Win32 Software Development Kit (SDK) for:
- Microsoft Windows 95
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 true particularly when you do not have the source code for the DLL so that you can port it to Win32. This article discusses the mechanism by which 32-bit DLLs can call 16-bit DLLs. The mechanism is called a thunk and the method implemented under Windows 95 is called a flat thunk.
The following describes the three major steps involved in creating a flat thunk:
1. Create the thunk script.
2. Build the 32-bit DLL.
3. Build the 16-bit DLL.
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 an exported function in the 16-bit DLL. When the function in the 16-bit DLL returns, it returns back to the 32-bit DLL, which in turn returns back to the Win32 application. The 32-bit and 16-bit DLLs work by calling the Windows 95 32-bit and 16-bit kernels to handle all of the low-level details necessary to make the transition from 32-bit to 16-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 two flags of -DIS_32 and -DIS_16. This allows you to create both the 32-bit and 16-bit object modules. These object modules are linked in the 32-bit and 16-bit DLLs, respectively. The following diagram summarizes the files involved in building the DLLs:
+------------+
| 32to16.thk |
+------------+
|
+------------+
| 32to16.asm |
+------------+
/ \
-DIS_32 / \ -DIS_16
/ \
+-----------+ +-----------+
| 32THK.obj | | 16THK.obj |
+-----------+ +-----------+
/ \
+-------+ +-------+ +-------+
| APP32 | -> | DLL32 | -- THUNK -- | DLL16 |
+-------+ +-------+ +-------+
You need to create a script that can be used by the Thunk compiler to create a thunk. A thunk script is a text file that contains type definitions, the function prototypes of the functions you wish to call via thunks and a specification of the direction of the parameters for each function. For example, some functions require both input and output parameters while others may only require input parameters. Thunk scripts use special syntax to describe whether parameters are input, output, or both input and output.
A thunk script for 32->16 thunks begins with the following statement:
enablemapdirect3216 = true;
The following example shows a thunk script for a function that has no parameters:
enablemapdirect3216 = true;
void MyThunk16()
{
}
C language: void WINAPI MyThunk16(void);
C++ language: extern "C" void WINAPI MyThunk16();
enablemapdirect3216 = true;
typedef int BOOL;
typedef char *LPSTR;
BOOL MyThunk16(LPSTR lpstrInput, LPSTR lpstrOutput)
{
lpstrInput = input; // optional; input is default
lpstrOutput = output;
}
The following thunk script uses more complex parameter types such as structures. This example also shows how to specify input and output parameters.
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 Thunk compiler usage is as follows:
thunk.exe /options <inputfile> -o <outputfile>
thunk -t thk 32to16.thk -o 32to16.asm
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;
}
definition (.def ) file for the 32-bit DLL. For example:
thk_ThunkData32
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.
thunk -t thk 32to16.thk -o 32to16.asm
a 32-bit object module. For example:
ml /DIS_32 /c /W3 /nologo /coff /Fo thk32.obj 32to16.asm
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.
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;
}
definition (.def) file for the 16-bit DLL. For example:
C16ThkSL01 = KERNEL.631
ThunkConnect16 = KERNEL.651
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
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.
thunk -t thk 32to16.thk -o 32to16.asm
16-bit object module. For example:
ml /DIS_16 /c /W3 /nologo /Fo thk16.obj 32to16.asm
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.
For information about how to debug flat thunks, please refer to the following article in the Microsoft Knowledge Base:
ARTICLE-ID: Q133722
TITLE : HOWTO: Debug Flat Thunks
Keywords : kbnetwork kbprg kbtshoot kbAPI kbKernBase kbSDKPlatform kbThunks kbNetAPI kbGrpNet kbGrpKernBase
Issue type : kbhowtoLast Reviewed: September 11, 1998