A.3.5.1 DLLs in Install and Shell Sections

For install and shell sections, the LoadLibrary, FreeLibrary, and LibraryProcedure commands are available to load and unload the library module, and to call a function within the library. The following shows the syntax for these commands:

LoadLibrary Syntax

The LoadLibrary command loads the specified library file, and returns a handle to the loaded module. If the library file cannot be located, the Setup program displays an error message and terminates. The syntax of the LoadLibrary command is:

LoadLibrary DiskName DLLPath LibHandle 

DiskName

String to prompt the user to insert a disk. This string is used only if DLLPath indicates that the specified file is on a floppy disk (for example, a:\Setupdll.dll) and the file is not found on the disk that is present.

DLLPath

The full path of the DLL file.

LibHandle

Receives the library handle. This handle identifies the library module in the LibraryProcedure and FreeLibrary commands, and it can also be used to identify the library module in a detect section.

For example:

LoadLibrary "Setup Disk #1" a:\setupdll.dll LibHandle
 

FreeLibrary Syntax

The FreeLibrary command unmaps the specified library module, invalidating the handle. The syntax of the FreeLibrary command is:

FreeLibrary LibHandle 

LibHandle

INF variable that identifies the loaded library module. This value is returned by the LoadLibrary command.

For example:

FreeLibrary $(LibHandle)
 

LibraryProcedure Syntax

The LibraryProcedure command calls an exported function in the specified DLL. The syntax of the LibraryProcedure command is:

LibraryProcedure Result LibHandle FunctionName [Args]*

Result

Receives the value of a text string returned by the DLL function.

LibHandle

INF variable that identifies the loaded library module. This value is returned by the LoadLibrary command.

FunctionName

Name of the DLL function to call (case-sensitive).

Args

Zero or more argument strings.

For example:

LibraryProcedure Result $(LibHandle) DLLFunc $(Arg0) $(Arg1)
 

The DLL function called by the LibraryProcedure command must provide a function whose prototype is shown below. Note that this prototype is different from that used for DLL functions called from a detect section.

BOOL PASCAL FunctionName(cArgs, lpszArgs[], *lpszTextOut)
DWORD cArgs;
LPSTR lpszArgs[];
LPSTR *lpszTextOut);

cArgs

The number of arguments in the lpszArgs array.

lpszArgs[]

An array of string arguments.

lpszTextOut

Receives a pointer to the result text. The DLL function must set this to point to a valid buffer (not NULL), although the buffer may be empty.

The function should return TRUE if successful or FALSE if an error occurs. The function is responsible for managing the memory allocated for the text buffer pointed to by lpszTextOut. If the function is successful, it can fill the lpszTextOut buffer with an arbitrary string, and the Setup program copies the text into the INF symbol table where it can be accessed using the Result variable. If an error occurs (that is, the function returns FALSE), the function should fill the lpszTextOut buffer with a descriptive error string. In this case, the Setup program’s default handling is to display the error string in a dialog box. This is treated as a noncritical error, with execution continuing and the value of the Result variable set to ERROR. This default error handling is overridden if the INF script has defined a FLibraryErrCtl variable with a value greater than zero. In this case, the error string is assigned to the Result variable, and the Setup program does not display the dialog.