Calling a DLL File Function

InstallShield 2016

There are three rules you must remember when you are calling DLL file functions from your InstallScript installation script:

•

The maximum length of the DLL file name is 33 characters; the maximum length of the function name is 63 characters.

•

The installation cannot accept a composite parameter (that is, a parameter with a width exceeding 4 bytes) when calling a DLL file. However, a parameter can be a pointer that points to a composite structure.

•

A string variable whose address is stored in a pointer variable cannot be changed by passing the pointer to a DLL file function. To allow a DLL file function to change the value of a string variable, pass the variable itself as an argument to the function, after declaring the data type of that argument specifying the BYREF operator.

To call a DLL file function from your script:

Add the DLL file to your project as a support file if you have not already done so. For more information, see Adding Support Files.

In the View List under Behavior and Logic, click InstallScript.

In the InstallScript explorer, click the InstallScript file (.rul) that should call the DLL function.

At the beginning of the script, prototype the function using the following syntax:

prototype [CallingConvention] [ReturnType] DLLName.FunctionName( ParamType1, ParamType2, ... );

For example:

prototype BOOL MyDLL.MyFunction( INT, INT, INT );

You can specify the calling convention to be cdecl or stdcall. If you do not specify a calling convention, InstallShield uses stdcall.

Note that the DLL file name is case-sensitive; for example, the script compiler treats MyDLL.MyFunction and mydll.MyFunction as different functions. When prototyping functions from User32.dll, Gdi32.dll, or Kernel32.dll, you may use the keywords USER, GDI, and KERNEL in place of the DLL file name.

You can specify the return type to be any InstallScript data type except LIST. If you are declaring a DLL file function call in which a wide-character string argument or a Unicode string argument is expected, use the wstring data type. If you do not specify a return type, the installation assumes that the DLL file function returns a 4-byte value.

Load the DLL file by calling the UseDLL function. For example:

UseDLL( SUPPORTDIR ^ "MyDLL.dll" );

Note • You do not need to load _isuser.dll, _isres.dll, or Windows API DLL files, such as User32.dll, Gdi32.dll, and Kernel32.dll. Do not call UseDLL and UnUseDLL to load and unload these DLL files.

Call the function as you would call any other function. For example:

bResult = MyDLL.MyFunction( nInt1, nInt2, nInt3 );

It is recommended that you include the DLL file name in the function call, as in the preceding example. If your script declares functions with the same name from different DLL files, calling the function without including the DLL file name results in a compiler error.

If the installation does not find the called function in the DLL file, the installation raises an exception, which you can handle by using a try...catch...endcatch block.

After all script calls to the DLL have been made, unload the DLL file by calling UnUseDLL. For example:

UnUseDLL( SUPPORTDIR ^ "MyDLL.dll" );

Note • You can use the IS_NULLSTR_PTR variable to pass a null pointer to an external DLL function or Windows API through a parameter that has been prototyped as an InstallScript string. For more information, see IS_NULLSTR_PTR.

Calling a DLL File Function

InstallShield 2016 Help Library

August 2016