You might want your DLL to receive notification of Viewer events (for example, when the user selects a jump or changes input focus to an application other than Viewer). To do this, you add a LDLLHandler function to the DLL. The LDLLHandler function has the job of processing messages sent from Viewer to the DLL.
When the user clicks the Call HelloWorld hot spot in DLLDEMO.MVB, Viewer loads DLLDEMO.DLL and looks for a function named LDLLHandler. If Viewer finds LDLLHandler, it calls LDLLHandler. A sample LDLLHandler function is defined in the DLLDEMO.C sample file provided with Viewer.
Note:
To debug your DLL or observe any of the operations described in this section, you can compile DLLDEMO for the CodeView for Windows symbolic debugger and open the DLL in CodeView while you view the sample title. See the DLLDEMO.C file for specific instructions.
The LDLLHandler function is defined in DLLDEMO.C as illustrated in the following example:
PUBLIC LONG PASCAL EXPORT LDLLHandler(
WORD wMsg,
LONG lParam1,
LONG lParam2)
{
switch(wMsg) {
case DW_WHATMSG:
return DC_INITTERM | DC_JUMP;
case DW_INIT:
return TRUE;
case DW_TERM:
return TRUE;
case DW_ACTIVATE:
return TRUE;
case DW_CHGFILE:
return TRUE;
}
return FALSE;
}In this definition, wMsg identifies the message Viewer has sent to the DLL. The two LONG parameters are passed with the message and depend on the message type.
When the user first clicks the Call HelloWorld hot spot, Viewer calls LDLLHandler with the wMsg parameter set to DW_WHATMSG. This message asks the DLL what types of Viewer messages it wants to receive. LDLLHandler should return one or more of the flags in the following table with this information. The Viewer uses the flags returned by LDLLHandler to determine which messages the DLL wants to receive in the LDLLHandler function.
| LDLLHandler Returns | Viewer Sends |
Description |
| DC_MINMAX | DW_MINMAX, DW_SIZE | Minimize, maximize, or resize Viewer | |
| DC_INITTERM | DW_INIT, DW_TERM | Initialize or terminate DLL | |
| DC_JUMP | DW_STARTJUMP, DW_ENDJUMP, DW_CHGFILE, Jump or change .MVB file | ||
| DC_ACTIVATE | DW_ACTIVATE | Give Viewer or another application input focus | |
| DC_CALLBACKS | DW_CALLBACKS | Give DLL access to Viewer entry points (see “Calling Viewer Internal Functions,” later in this chapter, for more information) | |
You combine these flags using the standard C bitwise-OR (|) operator. For example, many DLLs request notification when Viewer is about to initialize or terminate them. The sample LDLLHandler function requests this notification and asks to be notified when the user has moved the input focus to or from Viewer. It processes the DW_WHATMSG message as follows:
case DW_WHATMSG:
return DC_INITTERM | DC_ACTIVATE;The remainder of this section looks at the different Viewer messages that LDLLHandler processes.
The DC_INITTERM flag tells Viewer that the DLL should receive initialization and termination messages.
After LDLLHandler returns a DC_INITTERM flag, Viewer sends a DW_INIT message. This message tells LDLLHandler to perform any required initialization operations (such as initializing variables or loading strings). The lParam1 and lParam2 parameters are not used, and the return value has no meaning.
If LDLLHandler returns FALSE, Viewer unloads the DLL and stops sending messages. If LDLLHandler returns TRUE, the DLL remains loaded.
In the DLLDEMO sample, LDLLHandler returns TRUE for this message.
When the user ends a Viewer session, Viewer sends a DW_TERM message. This message tells LDLLHandler to perform any required cleanup operations before the DLL is unloaded from memory. The lParam1 and lParam2 parameters are not used, and the return value has no meaning.
The DC_MINMAX flag tells Viewer that the DLL should receive messages when the user minimizes, maximizes, or resizes the Viewer window.
Viewer sends the DLL a DW_MINMAX message if the user minimizes or maximizes the context window.
The lParam1 parameter to DW_MINMAX indicates which operation was performed: 1L for maximized or 2L for minimized.
The lParam2 parameter is not used.
If LDLLHandler returns TRUE for this message, Viewer continues sending this message throughout the remainder of the session; if LDLLHandler returns FALSE, Viewer stops sending it.
Viewer sends the DLL a DW_SIZE message if the user resizes the context window.
The lParam1 message specifies the horizontal size of the window in the low-order word and the vertical size in the high-order word.
The lParam2 parameter is not used.
If LDLLHandler returns TRUE for this message, Viewer continues sending this message throughout the remainder of the session; if LDLLHandler returns FALSE, Viewer stops sending it.
The DC_JUMP flag tells Viewer that the DLL should receive messages when the user executes a jump in the title.
Viewer sends the DLL a DW_STARTJUMP message after the user executes a jump. The parameters to DW_STARTJUMP are not used.
If LDLLHandler returns TRUE for this message, Viewer continues sending this message throughout the remainder of the session; if LDLLHandler returns FALSE, Viewer stops sending it.
Viewer sends the DLL a DW_ENDJUMP message after it displays the jump-destination topic.
The lParam1 parameter specifies the byte offset of that topic within the title's file system. This value can be passed to the LSeekHf function (defined in the DLL.H file) to perform a seek to that topic within the file.
The lParam2 parameter specifies the position of the scroll box in the topic. This value can be used in any of the standard Windows scrolling functions that accept scroll-position parameters.
If LDLLHandler returns TRUE for this message, Viewer continues sending this message throughout the remainder of the session; if LDLLHandler returns FALSE, Viewer stops sending it.
Viewer sends the DLL a DW_CHGFILE message if the user selects Open from the File menu to change .MVB files or jumps to a topic in a different .MVB file. If the message is the result of a jump to a new file, the Viewer sends the DW_CHGFILE message between the DW_STARTJUMP and DW_ENDJUMP messages.
The lParam1 parameter specifies a long pointer to the .MVB filename. The lParam2 parameter is not used.
If LDLLHandler returns TRUE for this message, Viewer continues sending this message throughout the remainder of the session; if LDLLHandler returns FALSE, Viewer stops sending it.
The DC_ACTIVATE flag tells Viewer that the DLL should receive a DW_ACTIVATE messages when the user gives either Viewer or another application the input focus.
The lParam1 parameter to the DW_ACTIVATE message specifies whether Viewer received (nonzero LONG value) or lost (0L) the input focus. The lParam2 parameter is not used.
If LDLLHandler returns TRUE for this message, Viewer continues sending this message throughout the remainder of the session; if LDLLHandler returns FALSE, Viewer stops sending it.