UseDLL

InstallShield 2018 » InstallScript Language Reference

Important • For important information regarding the use of UseDLL function and the current directory, see Current Directory Removed from DLL Search Path to Safeguard Against DLL Preloading Attacks.

The UseDLL function loads a .dll file into memory. After the .dll file has been loaded into memory, your installation script can call a function from that .dll file. Note that if the .dll file that is specified by szDLLName requires other .dll files, those other .dll files must reside in the folder from which the .dll file attempts to load them. Normally this will be the current folder. To ensure that those .dll files can be located, call ChangeDirectory to change the current folder to the location of those .dll files before calling UseDLL. Failure to do so may prevent the .dll file from loading properly.

Each time that you load a .dll file into memory, the .dll file’s lock count is incremented. The lock count identifies the number of applications that are using the .dll file. You should call UnUseDLL to unload a .dll file as soon as you are done using it. If you do not unload a .dll file when you are done with it, the .dll file will remain in memory when no applications need it, thereby wasting system resources. Every call to UseDLL should have a matching call to UnUseDLL in the script.

Caution • Microsoft Windows system .dll files, such as User32.dll, Gdi32.dll, and Kernel32.dll, are loaded and unloaded automatically by Windows. Do not call UseDLL and UnUseDLL to load and unload these .dll files.

Syntax

UseDLL ( szDLLName );

Parameters

UseDLL Parameters

Parameter

Description

szDLLName

Specifies the name of the .dll file to be loaded. If you do not specify an extension, the InstallScript engine assumes that the file has the extension .dll or .exe. Including a path in this parameter is recommended but optional. If the path for the .dll file is not specified in this parameter, the InstallScript engine searches for the .dll file using the same search order that the Windows API function LoadLibrary uses. For more information regarding the search order, see the description of this Windows API function on MSDN.

To include the .dll file in your installation, add it to the appropriate subfolder of the Language Independent folder in the Support Files view. When the installation is running on a target system, the .dll file is available in the temporary directory that is specified by SUPPORTDIR. You can then append the .dll file name to SUPPORTDIR as follows in order to reference the .dll file:

szDLLName = SUPPORTDIR ^ "TheDLL.dll";    UseDLL (szDLLName);

If you do not place your .dll file into your installation (by inserting it into the appropriate folder in the Support Files view), you can instead distribute the file along with the files of your application and then load it from the target system. However, if you do so, you must specify the location to which you install the .dll file so that your installation can reference it. You must also ensure that your installation does not attempt to load the .dll file before it has been transferred to the target system.

Note • The szDLLName parameter does not support uniform resource locators (URLs).

Return Values

UseDLL Return Values

Return Value

Description

0

Indicates that the function successfully loaded the .dll file into memory.

< 0

Indicates that the function was unable to load the .dll file into memory.

If UseDLL fails, the most likely cause is that the .dll file was not found. If this happens, make sure that the correct path is specified in the parameter szDLLName.

Another common cause of failure that is associated with using .dll files is related to .dll file dependencies—.dll files that are accessed by the .dll file that you load. If the .dll files that your .dll file must access are not loaded or found, your .dll file call may fail. If this occurs, make sure that the other .dll files are on the system and that they are accessible.

If the script exits or terminates before properly unloading the .dll file with UnUseDLL, the .dll file will be locked in memory. If you attempt to access the .dll file again, your script may fail. You must remove the .dll file from memory by restarting Windows.

Current Directory Removed from DLL Search Path to Safeguard Against DLL Preloading Attacks

Starting in InstallShield 2018, to safeguard installations against DLL preloading attacks, InstallShield has removed the current directory from the standard DLL search path by calling the SetDllDirectory Windows API with an empty string ("").

If a DLL links implicitly to the other DLLs, or loads them dynamically using LoadLibrary() without specifying a fully qualified path name, the UseDLL() InstallScript function cannot load the dependencies from the current working directory.

You can work around this issue by prototyping SetDllDirectoryW (prototype number kernel32.SetDllDirectoryW(wstring); ) and call it with SUPPORTDIR to get the support folder to be in the DLL load search path.

In InstallShield 2018, the following changes have been made:

The DLL_DIRECTORY_SUPPORTDIR constant was added to the Enable function so that customers can explicitly opt-in to using SUPPORTDIR as a DLL directory.
The DLL_DIRECTORY_SUPPORTDIR constant was added to the Disable function so that customers can explicitly opt-out to using SUPPORTDIR as a DLL directory.
The SetDllDirectory (szPathName) wrapper function was added so that customers can explicitly opt-in to using any directory as a DLL directory. If the parameter is an empty string (""), the call removes the current directory from the default DLL search order.

See Also