WaitForApplication

InstallShield 2016 » InstallScript Language Reference

The WaitForApplication function waits for a running application to terminate before returning.

If the function fails to wait for the application to terminate before returning, verify that the application does not terminate until other sub-applications launched by the application terminate. The WaitForApplication function monitors the process handle of the specified application; if the application passes control to a secondary application or process and then terminates, the function returns immediately.

Syntax

WaitForApplication( byval number hProcess, byval number dwProcessId, byval number nTimeOut, byval number nOptions );

Parameters

WaitForApplication Parameters

Parameter

Description

hProcess

Specifies the process handle of the running process for which to wait. (If the application was launched with LaunchAppAndWait or LaunchApp, this handle is returned in the LAAW_PROCESS_INFORMATION.hProcess member.)

dwProcessId

Specifies the process ID of the running process for which to wait. You need to specify a non-zero value for this parameter only if you specify LAAW_OPTION_WAIT_INCL_CHILD in nOptions.

If the application was launched with LaunchAppAndWait or LaunchApp and the process ID can be determined (as described for the description of LAAW_OPTION_WAIT_INCL_CHILD), this handle is returned in the LAAW_PROCESS_INFORMATION.dwProcessId member.

nTimeOut

Specifies the maximum amount of time (in milliseconds) to wait for the application to complete before returning. If this amount of time passes before the application terminates, the function ends the wait and returns failure. You can specify INFINITE to indicate that the function should wait indefinitely. (You can also pass the LAAW_PARAMTERS.nTimeOut value to mimic the behavior of the LaunchAppAndWait function.)

nOptions

Pass one of the following predefined constants in this parameter. You can combine these constants by using the bitwise OR operator ( | ), with the following exceptions: you cannot combine LAAW_OPTION_NOWAIT with LAAW_OPTION_WAIT.

• LAAW_OPTION_WAIT—Specifies that the function should wait until the specified application has terminated.

Note • If the specified applications fails to terminate and nOptions is set to LAAW_OPTION_WAIT (and nTimeOut is set to INFINITE), the installation will wait indefinitely for the launched application to complete.

• LAAW_OPTION_NOWAIT—Specifies that the function should return immediately.
• LAAW_OPTION_USE_CALLBACK—Causes the function to call the OnLaunchAppAndWaitCallback event every second, or whatever interval you set for the LAAW_PARAMETERS.nCallbackInterval member, while waiting for the application to terminate.
• LAAW_OPTION_WAIT_INCL_CHILD—Indicates that the function should wait for the launched application and any of its direct child processes.

When LAAW_OPTION_WAIT_INCL_CHILD is used, the function detects and waits for only direct child processes of the launched process—not for any additional child processes that are launched by child processes of the initially launched process.

Note that to detect and wait for child processes with LAAW_OPTION_WAIT_INCL_CHILD, the function must receive or be able to determine the process ID of the launched process. Therefore, in order for this option to work, if dwProcessId is not specified, the Windows API GetProcessId must be available on the system so that the function can determine the process ID. According to the Windows API documentation, GetProcessId is available on Windows XP SP1 and later and Windows Server 2003 and later. If this API is not available, LAAW_OPTION_WAIT_INCL_CHILD behaves as LAAW_OPTION_WAIT.

You can specify any LaunchApplication option; however, only the aforementioned options will have any effect.

Return Values

WaitForApplication Return Values

Return Value

Description

>= ISERR_SUCCESS

The application terminated and the function returned as a result.

< ISERR_SUCCESS

The function returned as a result of something other than the application terminating. You can check the value of LAAW_PARAMETERS.nWaitResult to determine additional information:

• WAIT_OBJECT_0—Indicates that the application terminated.
• WAIT_OBJECT_0 + 1—Indicates that the installation received a message to terminate.
• WAIT_TIMEOUT—Indicates that the timeout interval was reached or the callback function returned LAAW_CALLBACK_RETURN_END_WAIT. Check the value of LAAW_PARAMETERS.bCallbackEndedWait to determine which ended the wait.

InstallShield 2016 Help Library

May 2017

 Copyright Information | Flexera Software

Open topic with navigation