Registers a function within a dynamic-link library (DLL) as a Help macro. Registered functions can be used in macro hot spots or footnotes within topic files or in the [CONFIG] section of the Help project file, the same as standard Help macros.
Note:
The RegisterRoutine macro ignores all return values.
Syntax
RegisterRoutine("DLL-name", "function-name", "parameter-spec")
RR("DLL-name", "function-name", "parameter-spec")
Parameter | Description |
DLL-name | String specifying the filename of the DLL being called. 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. For more information, see “How Help Locates .DLL and .EXE Files” in Chapter 14, “Help Macros.” |
|||
function-name | String specifying the name of the function you want 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 | |
i | Signed short integer | BOOL (also C int or short) | |
I | Signed long integer | LONG, LPARAM, LRESULT | |
s | Near pointer to a null-terminated text string | PSTR, NPSTR | |
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. |
To determine the data type of the function’s parameters, consult the application programming interface (API) documentation for the DLL, or ask the person who developed the DLL. When using Windows functions with Windows Help, be sure that you fully understand how the function will affect Help. For information on Windows functions, their parameters, and parameter types, see the Microsoft Windows version 3.1 Software Development Kit.
Example
The following DLL call registers a routine named PlayAudio in the DLL named HELPLIB.DLL:
RegisterRoutine("helplib", "PlayAudio", "SIU")
Comments
If Windows Help cannot find the DLL, it displays an error message and does not perform the call. When loading DLLs, Help looks for a routine first in the directory from which Help was started. Therefore, WINHELP.EXE can be located anywhere—even on a drive not on the user’s machine—and Help will look for DLLs in that directory first. Generally, it is not a good idea to place application-specific DLLs in the Windows directory or in the Windows SYSTEM directory.