InstallAware for Windows Installer

Design Time Exports

The functions which must be exported by the design time DLL and their expected behavior is described below.

CompileTimeBuild

This function is called when the project is being compiled. The function should copy the necessary files for its operation, modify the Windows Installer database if necessary, and indicate whether it will require access to setup files during installation.

bool WINAPI CompileTimeBuild(
	int MSIHandle, 
	const char* State,
	const char* BuildPath, 
	bool Build, 
	bool* Fetch
);

MSIHandle

Handle to the Windows Installer database being currently generated.

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 also located in this DLL.

BuildPath

The full path to the folder where the plug-in must copy its build files to. At a minimum, the plug-in should copy its Run-Time DLL to this build location. The plug-in may also copy other files as needed (for instance, if the plug-in installs any files, it should also copy those files).

Build

Indicates whether files should actually be copied.

Fetch

If the plug-in requires access to the setup media (that is, the files it copied to BuildPath, excluding the runtime DLL file) for the current value of the State parameter, the plug-in should set this variable to TRUE. Otherwise, the variable should be set to FALSE.

InstallAware uses this information to determine if a web media block should be downloaded at runtime while the plug-in is executing.

Return

The function should return TRUE if the plug-in's own compilation succeeded or FALSE if it failed. Returning FALSE from this plug-in will immediately abort the InstallAware project compilation currently taking place with a generic plug-in compilation error. Since there is no field to pass detailed error information when failing the project compilation from a plug-in, you may display a message box or write to a custom log before failing the compilation.

CompileTimeBuildW

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.

bool WINAPI CompileTimeBuildW(
	int MSIHandle, 
	const wchar* State,
	const wchar* BuildPath, 
	bool Build, 
	bool* Fetch
);

CompileTimeBuildExW

This function is called when the project has nearly finished building in its entirety and all web media blocks have been successfully generated. A compile is not necessarily followed by a full build; this function will not be called unless a full build is being done.

This function is not mandatory and will be called only if exported by the plug-in compile time DLL file, and if the plug-in has already been registered as a download handler using the Use Download Engine command. If exported, this function must be Unicode.

This function is primarily intended for custom download handlers which may need to do post-processing on built web media blocks and store additional data in setup build folders for runtime use.

bool WINAPI CompileTimeBuildExW(
	const wchar* ProjectFolder,
	const wchar* BuildFolder,
	const wchar* State
);

ProjectFolder

The full path to the folder containing the project being built.

BuildFolder

The full path to the root folder of the nearly finalized build process.

State

The state information of the plug-in represented as a string, as defined in the Use Download Engine command. This state parameter is opaque to InstallAware.

Return

The function should return TRUE if the plug-in's own build succeeded or FALSE if it failed. Returning FALSE from this plug-in will immediately abort the InstallAware project compilation currently taking place with a generic plug-in build error. Since there is no field to pass detailed error information when failing the project compilation from a plug-in, you may display a message box or write to a custom log before failing the compilation.

CompileTimeBuildEy (Deprecated)

This function receives the code signing settings of the active project, and is primarily intended for use when the plug-in being invoked must directly perform code signing on some or all of its payload, in a manner which would be difficult to achieve through other means (such as Build Events).

This function is optional.

This function has been deprecated.

Instead of manually implementing code signing using the information passed to your plug-in via this deprecated function, you may instead implement the new CompileTimeSign function to have any file directly code signed by the native build process. This approach has the added benefit of supporting any current and future code signing standard, including Code Signing Hooks; exactly as specified in the InstallAware IDE Build Settings for the setup being compiled.

void WINAPI CompileTimeBuildEy(
	const wchar* FileName,
	const wchar* Password,
	const wchar* TimeStampURL
);

FileName

Path to the PFX/P12 certificate that will be used to code sign the active project.

Password

The password of the certificate being used to sign the active project.

TimeStampURL

The URL of the time stamp service provider for code signing.

Remarks

This function must be implemented as Unicode.
This function will be called immediately before CompileTimeBuildW is called. It will not be called when your plug-in has only implemented CompileTimeBuild.
Store the information supplied by this function for immediate use upon the subsequent invocation of your library.
This function will not be called if a non-PFX/P12 type certificate is being used (such as Extended Verification certificates or legacy SPC/PVK pairs). Use the new CompileTimeSign function instead.

CompileTimeSign

This function receives the address of a callback function you may invoke at any time during the execution of your CompileTimeBuildW function to directly sign any file you are adding to your payload, using the same settings exactly as specified in the InstallAware IDE Build Settings for the setup being compiled.

This function is optional.

This function replaces the deprecated CompileTimeBuildEy function, offering the added benefit of supporting any current and future code signing standard, including Code Signing Hooks.

void WINAPI CompileTimeSign(
	lpfnCallback SignerCallback
);

SignerCallback

Address of the callback function you may invoke to natively code sign any file that is part of your payload. Store this address for any future invocations of the supplied function.

bool WINAPI SignerCallback(
	const wchar* FileName
);

FileName

Pass the full path to the file to natively code sign when invoking the code signing callback passed to your CompileTimeSign function.

Return

The callback function returns TRUE to indicate code signing succeeded, and FALSE otherwise.

Remarks

The callback function is implemented as Unicode.
This function will be called immediately before CompileTimeBuildW is called. It will not be called when your plug-in has only implemented CompileTimeBuild.

DesignTimeEdit

This function is called when the plug-in command is being added to the script for the first time, or an already existing command edited. The function should display a plug-in defined window enabling the user to configure plug-in settings (such as, what the plug-in does at install time). These settings will be passed back to the caller enabling their storage in a persistent medium.

int WINAPI DesignTimeEdit(
	int Window,
	const char* State,
	char* NewState
);

Window

Handle to parent window, the InstallAware IDE.

State

The existing 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 this function.

If the command is being added to the script for the first time, this parameter will be NULL. The plug-in should initialize its user interface and reflect default plug-in settings, or display the settings previously configured by the user.

NewState

The new 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 this function.

The plug-in should generate this string based on the settings configured by the user in the plug-in defined window. If NewState is not NULL, the plug-in should pass the state string back to the caller. The caller will then store this state information for later use in setup projects and running setups.

Remarks

The DesignTimeEdit function will always be called twice:

The first call of the function will always have the NewState parameter set to NULL. The function should display its user interface, generate the NewState 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 NewState string.
If the user cancelled the operation in the plug-in user interface, the function should return -1 indicating that command insertion to the script was aborted. In this case, the function will not be called again, since it is not necessary to obtain state information anymore.
The second call of the function will always pass a non-NULL NewState parameter, with just enough space to hold the NewState string. In this second iteration, the function should not display a user interface at all. It should instead copy to the buffer pointed to by the NewState variable the NewState string it generated and stored in the first iteration. In the second iteration, the function should always return 0.

DesignTimeEditW

int WINAPI DesignTimeEditW(
	int Window,
	const wchar* State,
	wchar* NewState
);

DesignTimeText

This function returns custom plug-in text for display in the script editor. This function is optional.

int WINAPI DesignTimeText(
	const char* State,
	char* Text
);

State

The existing state of the plug-in represented as a string. This state parameter is opaque to InstallAware. The state parameter passed here has been previously generated by the plug-in in the DesignTimeEdit function.

Text

The human readable representation of the plug-in state, as will be displayed in the script editor.

Remarks

The DesignTimeText function will always be called twice:

The first call of the function will always have the Text parameter set to NULL. The function should parse the State parameter, generate the Text 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 Text string.
The second call of the function will always pass a non-NULL Text parameter, with just enough space to hold the Text string. In this second iteration, the function should not re-parse the State parameter at all. It should instead copy to the buffer pointed to by the Text variable the Text string it generated and stored in the first iteration. In the second iteration, the function should always return 0.

DesignTimeTextW

int WINAPI DesignTimeTextW(
	const wchar* State,
	wchar* Text
);

DesignTimeEditExW

This function is called when the plug-in download handler state string is being edited visually through the Use Download Engine command in the IDE. The function should display a plug-in defined window enabling the user to configure download handler settings (such as, how many download parts to use, what trackers to use for torrent/magnet downloads, and so forth). This function is optional.

int WINAPI DesignTimeEditExW(
	int Window,
	const char* State,
	char* NewState
);

Window

Handle to parent window, the InstallAware IDE.

State

The existing download handler state of the plug-in represented as a string. This download handler state parameter is opaque to InstallAware. The plug-in generates and returns download handler state information in this function.

This parameter may be NULL if no pre-defined download handler state information exists. The plug-in should initialize its user interface and reflect recommended download handler state settings.

NewState

The new download handler state of the plug-in represented as a string. This download handler state parameter is opaque to InstallAware. The plug-in generates and returns download handler state information in this function.

The plug-in should generate this download handler state string based on the settings configured by the user in the plug-in defined download handler state configuration window. If NewState is not NULL, the plug-in should pass the download handler state string back to the caller. The caller will then store this download handler state information for later use in setup projects and running setups.

Remarks

The DesignTimeEditExW function will always be called twice:

The first call of the function will always have the NewState parameter set to NULL. The function should display its user interface, generate the NewState 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 NewState string.
If the user cancelled the operation in the plug-in user interface, the function should return -1 indicating that download handler state string generation was aborted. In this case, the function will not be called again, since it is not necessary to obtain state information anymore.
The second call of the function will always pass a non-NULL NewState parameter, with just enough space to hold the NewState string. In this second iteration, the function should not display a user interface at all. It should instead copy to the buffer pointed to by the NewState variable the NewState string it generated and stored in the first iteration. In the second iteration, the function should always return 0.

AboutPlugIn

This function displays the plug-in about box, containing general and copyright information on the plug-in.

void WINAPI AboutPlugIn(
	int Window
);

Window

Handle to parent window, the InstallAware IDE.