PRB: Calling 32-bit Help Files from 16-bit Applications on NT

ID: Q188304

The information in this article applies to:

Microsoft Visual C++ for Windows, 16-bit edition, version 1.52
Microsoft Win32 Software Development Kit (SDK)

SYMPTOMS

This problem exists on Windows NT 4.0. When you call 32-bit Help files from 16-bit applications, the following error occurs:

This file is not a Windows Help File.

It is followed by another error:

A newer version of Help is needed to read this Help file.

CAUSE

16-bit Applications launch WinHelp.exe instead of the 32-bit Help engine, WinHlp32.exe. WinHelp.exe does not call WinHlp32.exe with the correct parameters to launch the 32-bit help file.

RESOLUTION

To workaround this problem, you can call WinHlp32.exe with command-line parameters. The following example demonstrates how to use the ShellExecute API in a C program:


   ShellExecute(hwnd, NULL, "winhlp32.exe", "-N2 c:\\test.hlp", "e:\\test",
   SW_SHOWNORMAL);

The first parameter, hwnd, is a valid window handle. The fourth parameter contains the command-line parameters. It specifies that the Help file "c:\test.hlp" should be launched and the topic with a ContextID of 2 displayed. You can find information on other command-line parameters for WinHlp32.exe in the Help files for the Microsoft Help Workshop (see REFERENCES). The fifth parameter in ShellExecute() points to a null- terminated string that specifies the default directory.

An alternative workaround is to write a generic thunk. Please see the MORE INFORMATION section for an example.

STATUS

Microsoft is researching this problem and will post new information here in the Microsoft Knowledge Base as it becomes available.

MORE INFORMATION

The following example demonstrates how to use generic thunking to call the exported function WinHelpA() directly. This function is exported from User32.dll. You can insert the following code into any 16-bit C++ application. WinHlp32() wraps the WinHelp() function and performs the generic thunk automatically.

Sample Code


   // Stdafx.h is assumed to exist and is assumed to include
   // <windows.h>. If not, include <windows.h> here instead:
   # include "stdafx.h"

   // WOW_HANDLE_TYPE enumerated type for WOWHandle32():
   typedef enum _WOW_HANDLE_TYPE {
   WOW_TYPE_HWND,
   WOW_TYPE_HMENU,
   WOW_TYPE_HDWP,
   WOW_TYPE_HDROP,
   WOW_TYPE_HDC,
   WOW_TYPE_HFONT,
   WOW_TYPE_HMETAFILE,
   WOW_TYPE_HRGN,
   WOW_TYPE_HBITMAP,
   WOW_TYPE_HBRUSH,
   WOW_TYPE_HPALETTE,
   WOW_TYPE_HPEN,
   WOW_TYPE_HACCEL,
   WOW_TYPE_HTASK,
   WOW_TYPE_FULLHWND
   } WOW_HANDLE_TYPE;

   // Typedef for kernel function pointers needed for
   // thunking (found in krnl386.dll):
   typedef DWORD (FAR PASCAL * LOADLIBRARYEX32W)(LPCSTR lpszLibFile,
      DWORD hFile, DWORD dwFlags);
   typedef DWORD (FAR PASCAL * GETPROCADDRESS32W)(DWORD hModule,
      LPCSTR lpszProc);
   typedef DWORD (FAR PASCAL * FREELIBRARY32W)(DWORD hLibModule);
   typedef DWORD (FAR CDECL  * CALLPROCEX32W)( DWORD, DWORD,
      DWORD, ... );
   // Typedef for Wow32 function pointer needed for converting
   // 16-bit window handle:
   typedef DWORD (FAR PASCAL * WOWHANDLE32)(WORD Handle,
      WOW_HANDLE_TYPE Type);

   // WinHelp32() function declaration:
   // Note: This loads WinHelpA() from User32.dll, and it requires
   // that you pass an ASCII string for lpszHelpFile. If you need to
   // use this function in a UNICODE application, you either have to
   // convert the string to ASCII or modify this function to accept a
   // UNICODE string. In the second case, you also have to load the UNICODE
   // version of WinHelp, WinHelpW().
   BOOL WinHelp32(HWND hwnd, LPCSTR lpszHelpFile,
      UINT fuCommand, DWORD dwData);

   // Function pointer to the ASCII version of WinHelp API call:
   typedef BOOL (FAR PASCAL * WINHELPA)(HWND, LPCSTR, UINT, DWORD);

   BOOL LoadGenericThunkFuncs();

   // Declare global function pointers:
   LOADLIBRARYEX32W lpfnLoadLibraryEx32W = NULL;
   GETPROCADDRESS32W lpfnGetProcAddress32W = NULL;
   FREELIBRARY32W lpfnFreeLibrary32W = NULL;
   CALLPROCEX32W lpfnCallProcEx32W = NULL;


   // WinHelp32 function definition - wrapper around WinHelpA().
   // See documentation for the WinHelp API for parameter information.
   BOOL WinHelp32(HWND hwnd, LPCSTR lpszHelpFile,
      UINT fuCommand, DWORD dwData)
   {
   static BOOL bFirstTime = TRUE;
   static BOOL bFuncsLoaded = FALSE;
   BOOL bSuccess = TRUE;
   DWORD hUser32Lib = NULL;
   DWORD hWow32Lib = NULL;
   DWORD hWnd32 = NULL;

   // Both WinHelpA and WOWHandle32 need thunking.
   WINHELPA hWinHelpA = NULL;
   WOWHANDLE32 hWOWHandle32 = NULL;

   if (bFirstTime)
   {
   // This is the first time the function is accessed.
   // Load global function pointers from kernel.
   bFuncsLoaded = LoadGenericThunkFuncs();
   bFirstTime = FALSE;
   }

   // Unless the thunking functions from kernel were successfully
   // loaded, the thunking code will not work.
   if (bFuncsLoaded)
   {
   // Load the User32.dll library where the 32-bit WinHelp()API
   // is located:
   hUser32Lib = lpfnLoadLibraryEx32W("user32.dll", NULL, 0);
   if (!hUser32Lib)
   bSuccess = FALSE;

   // Load the Wow32.dll library where WOWHandle32W() is located:
   hWow32Lib = lpfnLoadLibraryEx32W("wow32.dll", NULL, 0);
   if (!hWow32Lib)
   bSuccess = FALSE;

   if (bSuccess)
   {
   hWinHelpA = (WINHELPA)lpfnGetProcAddress32W(hUser32Lib, "WinHelpA");
   if (!hWinHelpA)
      bSuccess = FALSE;

   hWOWHandle32 = (WOWHANDLE32)lpfnGetProcAddress32W(hWow32Lib,
      "WOWHandle32");
   if (!hWOWHandle32)
      bSuccess = FALSE;
   }

   if (bSuccess)
   {
   // Call WOWHandle32W() to convert the 16-bit HWND to a 32-bit HWND:
   // Note: 2nd parameter 1(0x01) because the hwnd is passed by
   // reference.
   hWnd32 = (DWORD)lpfnCallProcEx32W(2, 1, (DWORD)hWOWHandle32,
      (DWORD)hwnd, (DWORD)WOW_TYPE_HWND);

   // Call WinHelp().
   // Note: 2nd parameter 2(0x010) because the lpszHelpFile is
   // passed by reference.
   bSuccess = lpfnCallProcEx32W(4, 2, (DWORD)hWinHelpA, hWnd32,
      (DWORD) lpszHelpFile, (DWORD) fuCommand, (DWORD) dwData);
   }

   if (hUser32Lib)
   lpfnFreeLibrary32W(hUser32Lib);
   if (hWow32Lib)
   lpfnFreeLibrary32W(hWow32Lib);
   }

   return bSuccess;
   }

   // LoadGenericThunkFuncs() dynamically loads the functions
   // necessary to perform the generic thunk from "kernel"
   // located in krnl386.dll.
   BOOL LoadGenericThunkFuncs()
   {
   BOOL bSuccess = TRUE;
   HINSTANCE hInst = NULL;

   hInst = LoadLibrary("kernel");
   if (!hInst)
   bSuccess = FALSE;

   if (bSuccess)
   {
   lpfnLoadLibraryEx32W = (LOADLIBRARYEX32W) GetProcAddress(hInst,
      "LoadLibraryEx32W");
   bSuccess = (lpfnLoadLibraryEx32W != NULL);

   lpfnGetProcAddress32W = (GETPROCADDRESS32W) GetProcAddress(hInst,
      "GetProcAddress32W");
   bSuccess = (bSuccess && (lpfnGetProcAddress32W != NULL));

   lpfnFreeLibrary32W = (FREELIBRARY32W) GetProcAddress(hInst,
      "FreeLibrary32W");
   bSuccess = (bSuccess && (lpfnFreeLibrary32W != NULL));

   lpfnCallProcEx32W = (CALLPROCEX32W) GetProcAddress(hInst,
      "_CallProcEx32W");
   bSuccess = (bSuccess && (lpfnCallProcEx32W !=NULL));
   }

   return bSuccess;
   }

REFERENCES

The Microsoft Help Workshop is available for download from the Microsoft Software Library:

HCWSetup.exe

For more information about downloading files from the Microsoft Software Library, please see the following article in the Microsoft Knowledge Base:

Q119591 How to Obtain Microsoft Support Files from Online Services

For additional information, please see the following articles in the Microsoft Knowledge Base:

Q169020 32-bit Help Fails to Start When 16-bit Help Is Running

Q104009 Generic Thunks: Calling a Win32 DLL from a Win16 Application

Additional query words: kbHelpCompiler kbSDKWin32 kbVC152 kbDSupport kbdss

Keywords : kbcode kberrmsg kbfile
Version : winnt:1.52
Platform : winnt
Issue type : kbprb