Run-Time Exports

The functions which must be exported and called by the run-time DLL, and their assumed behavior, is described below.

PlugInProgressIndicator

This is a setup executable defined callback function. The plug-in will receive the address of the callback function in the RunTimeExecute function, also located in this DLL. It should periodically call this function to keep the setup user interface updated of the overall progress of the task the plug-in is performing.

typedef BOOL (WINAPI* lpPlugProgressIndicator)(
	int, 
	const char*
);

Integer Parameter

This parameter should contain the numeric representation of the overall task progress, where 0 is nothing and 100 is complete.

Char* Parameter

This parameter should contain a textual description of the currently executing task.

Boolean Return

The callback function will return TRUE if the plug-in is permitted to continue its task. If the setup has been cancelled by the user, the callback function will return FALSE. In this case, the plug-in should immediately end its task and clean up after itself.

PlugInProgressIndicatorW

This function is the Unicode version of the preceding ANSI function. The meanings of the function parameters are identical as in the preceding ANSI version.

The plug-in will receive the address of this callback function in the RunTimeExecuteW function.

typedef BOOL (WINAPI* lpPlugProgressIndicatorW)(
	int, 
	const wchar*
);

RunTimeExecute

This function will perform the actual plug-in task, and update script variables as necessary. It will be called at runtime by the setup executable.

int WINAPI RunTimeExecute(
	int Window,
	const char* Variables,
	const char* State,
	lpPlugProgressIndicator Progress,
	int* Return,
	char* NewVariables
);

Window

Handle to parent setup window.

Variables

This parameter contains the names and values of all variables used in the setup script as a comma delimited string list of the form <variable name>,<variable value>,...,<variable name>,<variable value>. If a variable name or value contains embedded spaces, the entire value will be enclosed in double quotes.

State

The state of the plug-in represented as a string. This state parameter is opaque to InstallAware. The plug-in generates and returns state information in the DesignTimeEdit function located in the design time DLL.

In essence, this variable tells the plug-in what to do.

Progress

Pointer to the progress callback function which the function must periodically call, both updating the setup user interface, and allowing the user to abort the operation if so required.

Return

Reserved. Set to 0.

NewVariables

The new state of the installation variables. The plug-in should modify the script variables list received in the Variables parameter and return it in this parameter if NewVariables is not NULL. Of course, if the plug-in did not change the state of any script variable, the plug-in should instead return a copy of the original Variables parameter.

If NewVariables is NULL, the plug-in should internally store the script variables. See the remarks for more information.

 Remarks

The RunTimeExecute function will always be called twice:

1. The first call of the function will always have the NewVariables parameter set to NULL. The function should perform its installation action, perpare the NewVariables string, and store it in a buffer. The function should return the length of the buffer as its result. This will enable the caller to allocate sufficient memory to hold the NewVariables string.
2. The second call of the function will always pass a non-NULL NewVariables parameter, with just enough space to hold the NewVariables string. In this second iteration, the function should not perform an installation action at all. It should instead copy to the buffer pointed to by the NewVariables variable the NewVariables string it generated and stored in the first iteration. In the second iteration, the function should always return 0.

RunTimeExecuteW

This function is the Unicode version of the preceding ANSI function. If available, InstallAware will always call the Unicode version instead of the preceding ANSI version. The meanings of the function parameters are identical as in the preceding ANSI version.

This function is not mandatory, however either the Unicode or the preceding ANSI version of this function must be implemented. Where you have implemented the Unicode version of this function, you do not need to implement the ANSI version.

int WINAPI RunTimeExecuteW(
	int Window,
	const wchar* Variables,
	const wchar* State,
	lpPlugProgressIndicatorW Progress,
	int* Return,
	wchar* NewVariables
);

RunTimeDownloadW

This Unicode function downloads the requested file at runtime. It will be called at runtime by the setup executable when a Web Media Block file is ready to be downloaded. All string parameters in this function are Unicode strings.

This function is required only for plug-ins which have registered as internal setup engine download handlers.

int WINAPI RunTimeDownloadW(
	int Window,
	const wchar* DownloadURL,
	const wchar* LocalFile,
	const wchar* ProxyServer,
	const wchar* ProxyPort,
	const wchar* ProxyUser,
	const wchar* ProxyPassword,
	const wchar* State,
	const bool ResumeBroken,
	lpPlugProgressIndicatorW DownloadProgress
);

Window

Handle to parent setup window.

DownloadURL

This parameter contains the full URL of the file to download.

LocalFile

This parameter contains the full local path for the downloaded file.

ProxyServer

If a proxy server is to be used, this parameter contains the address of the proxy server.

ProxyPort

If a proxy server is to be used, this parameter contains the port of the proxy server.

Please note that while this parameter is a string, the proxy port represented will be an integer.

ProxyUser

The user name for the proxy server, or empty if no user name is required.

ProxyPassword

The password for the proxy server, or empty if not password is required.

State

Any custom initialization data to be passed to the plug-in during the download process, represented as a string. This state parameter is opaque to InstallAware.

Variables used in this field will be resolved to their literal values before being passed to the plug-in at runtime.

The Use Download Engine command which activates a plug-in as a custom download handler sets this string to the value provided by the developer at design time.

ResumeBroken

If TRUE, requests that the plug-in attempt to resume broken downloads where possible.

If FALSE, requires that the plug-in discard any partially downloaded data - potentially to reattempt a previously corrupted download.

A plug-in may not honor to resume a broken download, but it must always honor a request to download a full, fresh copy of the data.

DownloadProgress

Pointer to the progress callback function which the function must periodically call, both updating the setup user interface, and allowing the user to abort the operation if so required.

Result

If the download was successful, set to 0. If the download failed, set to any other value such as 1.

The plug-in must report failures accurately, as otherwise the running setup process will be unable to invoke its own built-in download handler.

 Remarks

The RunTimeExecute function will always be called twice:

1. The first call of the function will always have the NewVariables parameter set to NULL. The function should perform its installation action, perpare the NewVariables string, and store it in a buffer. The function should return the length of the buffer as its result. This will enable the caller to allocate sufficient memory to hold the NewVariables string.
2. The second call of the function will always pass a non-NULL NewVariables parameter, with just enough space to hold the NewVariables string. In this second iteration, the function should not perform an installation action at all. It should instead copy to the buffer pointed to by the NewVariables variable the NewVariables string it generated and stored in the first iteration. In the second iteration, the function should always return 0.