When registering a DLL function, you provide Help the following information:
nDLL filename
nFunction name
nData type returned by the function
nNumber and type of function parameters
To register the DLL function, you enter a RegisterRoutine macro in the [CONFIG] section of the Help project file. (If you don’t register the DLL function in the [CONFIG] section, you must register it another way before using the function.) The RegisterRoutine macros are executed when the Help file is opened, so the registered functions are available during the entire Help session. You must register a DLL routine before using it, or the Help compiler will report an error when it encounters the unregistered macro in the RTF source files, and the macro will not work when executed in the built Help file.
The RegisterRoutine macro has the following syntax:
RegisterRoutine("DLL-name", "function-name", "parameter-spec")
Parameter | Description |
DLL-name | String specifying the name of the DLL in which the function resides. The filename must be enclosed in quotation marks. You can omit the .DLL filename extension.
Specify the directory only if necessary. Generally, DLLs are installed in the directory where Windows Help resides. See the next section, “How Help Locates .DLLs,” for more information. |
|||
function-name | String specifying the name of the function to use as a Help macro. The function name must be enclosed in quotation marks. | |||
parameter-spec | String specifying the formats of parameters passed to the function. Characters in the string represent C parameter types. Valid parameter types include the following: | |||
Character | Data Type | Equivalent Windows Data Type |
u | Unsigned short integer | UINT, WORD, WPARAM | |
U | Unsigned long integer | DWORD, RGBQUAD | |
i | Signed short integer | BOOL (also C int or short) | |
I | Signed long integer | LONG, LPARAM, LRESULT | |
S | Far pointer to a null-terminated text string | LPSTR, LPCSTR | |
v | Void (means no type; used only with return values) | None. Equivalent to C void data type. |
The parameter-spec must be enclosed in quotation marks. Windows Help checks the format string to ensure that it matches the function prototype defined in the DLL. (For more information about the RegisterRoutine macro, see Chapter 15, “Help Macro Reference.”) |
To determine the data type of the function’s parameters, consult the application programming interface (API) documenation for the DLL, or ask the person who developed the DLL. For information on parameter types of Windows functions, see the Windows version 3.1 SDK.
The HelloWorld function is defined as follows in the DLLDEMO.C file:
PUBLIC BOOL PASCAL EXPORT HelloWorld( LONG hwndContext, LPSTR lszHlpFile)
{
MessageBeep(0);
}
HelloWorld takes, as parameters, two internal Windows Help variables: a handle to the Windows Help context window and a pointer to the name of the .HLP file that Windows Help has opened. Although HelloWorld doesn’t do anything with these parameters, they illustrate the types of internal Windows Help variables you might pass to a DLL. For a complete list of these variables, see the “Windows Help Internal Variables section,” later in this chapter.
HelloWorld is registered in the DLLDEMO.HPJ Help project file as follows:
[CONFIG]
RegisterRoutine("dlldemo", "HelloWorld", "US")
As described above, the first parameter to RegisterRoutine is the DLL name (DLLDEMO); the second is the name of the function being registered; and the third is a format string representing the types of parameters in the function. Windows Help compares the parameter-spec with the function’s parameter types and issues an error if they don’t match.
The format string for the parameters to HelloWorld are U (unsigned long) for the LONG parameter and S for the LPSTR parameter. All internal variables that are handles should be declared in RegisterRoutine with a U specifier, even though they are normally WORDs, for upward compatibility with future versions of the Windows graphical environment. All internal string variables should be declared with an S specifier.