Accessing Windows Help Functions (DW_CALLBACKS)

If a DLL wants access to Windows Help internal functions, its LDLLHandler function handles the DW_WHATMSG message by returning a DC_CALLBACKS flag. In DLLDEMO.C, the LDLLHandler function requests access as follows:

case DW_WHATMSG:
           return DC_INITTERM | DC_CALLBACKS;

When it gets this flag, Windows Help sends a DW_CALLBACKS message to the DLL. The lParam1 parameter is a long pointer to an array containing pointers to each of the 16 internal Windows Help functions. The DLL.H file defines symbolic names for indexing each function in the array.

In processing the DW_CALLBACKS message, the LDLLHandler function calls a function named GetCallBacks to specify which functions it wants to access. GetCallBacks is defined as follows in DLLDEMO:

PUBLIC     BOOL PASCAL EXPORT GetCallBacks(
VPTR     VPtr,
LONG     lVersion)
{

     // hfs level:
     lpfn_HfsOpenSz       = VPtr[HE_HfsOpenSz];
     lpfn_RcCloseHfs      = VPtr[HE_RcCloseHfs];
     lpfn_RcLLInfoFromHfs = VPtr[HE_RcLLInfoFromHfs];

     // bag level routines
     lpfn_FAccessHfs =  VPtr[HE_FAccessHfs];
     lpfn_HfOpenHfs  =  VPtr[HE_HfOpenHfs];
     lpfn_LcbReadHf  =  (LPFN_LCBREADHF) VPtr[HE_LcbReadHf];
     lpfn_RcCloseHf  =  VPtr[HE_RcCloseHf];
     return TRUE;
}

The VPtr parameter in GetCallBacks is the lParam1 pointer passed by the DW_CALLBACKS message from Windows Help. The GetCallBacks function gets pointers to the following Windows Help internal functions, which it uses later in the example.

Function What it does

HfsOpenSz Opens the .HLP file system (the compound file containing the files internal to the Help file)
RcCloseHfs Closes the open .HLP file system
RcLLInfoFromHfs Maps a handle to the open .HLP file system (returned by HfsOpenSz) to low-level file information
FAccessHfs Determines whether a file within the .HLP file system is accessible
HfOpenHfs Opens a file within the .HLP file system
LcbReadHf Reads bytes from a file within the .HLP file system

Note:

This sample code does not take multiple instances of Windows Help into account. If more than one instance is started, the DLL receives different pointers to these callback functions—one pointer for each instance. You must keep track of which pointer is associated with each Windows Help instance. One way to do this is to create an array associating the task with the callback pointer.