|
Plug-In Authoring Overview
The InstallAware IDE and setups are plug-in extensible. This document describes how to develop plug-ins for extending InstallAware installations. To jump start your plug-in development:
- Click the InstallAware button, then choose New Project
Other. - On the tab, pick a plug-in template.
Plug-In Files
A plug-in consists of two DLLs:
- Design-Time/Compile-Time DLL. Invoked from the IDE while setup is being designed, and compiled.
- Run-Time DLL. Invoked from the running setup program while product is actually being installed.
More files may be present in the plug-in folder as required by the plug-in. These files may be support files for the DLLs, or files that the plug-in makes available to the running setup.
Both DLLs must be compiled as 32 bit binaries.
Design-Time/Compile-Time DLL
This DLL should:
- Display user interface, allowing programmer to configure plug-in options
- Participate in the build process, by copying the runtime dll, and required support files, to the build location
This DLL may include dependencies on other libraries.
Optional Enhancements
Beginning with InstallAware version , this DLL may also:
- Be invoked while setup is being built, immediately after the completion of Web Media Block generation, and right before the main setup package is finalized.
- Be invoked from the IDE to visually generate/edit a custom download handler state string for the Use Download Engine command.
Beginning with InstallAware version , this DLL may also:
- Receive information on the code signing settings used in the active project.
This DLL should:
- Perform the actual plug-in task while install is running
- Properly return updated state of variables to calling process
- Update progress for lengthy operations with callbacks
This DLL must not have any runtime dependencies. It should be able to carry out its task in any operating environment, since it will be called from the setup at runtime in a production environment.
Optional Enhancements
Beginning with InstallAware version , this DLL may also:
- Provide a custom handler to process internal setup engine downloads for Web Media Blocks.
Plug-In Registration
A plug-in should create keys in the system registry, letting the InstallAware development environment know of its existence.
HKEY_LOCAL_MACHINE
SOFTWARE
MimarSinan
InstallAware
2.0
Plug-Ins
{Plug-In Name}
(Default) = {Full Path to Plug-In Design-Time/Compile-Time DLL}
Action = {Plug-In Name}
Execute = {File Name (without path) to Plug-In Run-Time DLL}
Script = {Plug-In Script Display}
SupportsDownloads = {DWORD}
DefaultState = {Plug-In Download Handler Default State}
StateDescription = {Plug-In Download Handler State Description}
The key must be created in the 32 bit hive of the registry on a 64 bit operating system. Therefore, the registry structure above, which is provided for a 32 bit operating system, would need to be updated as follows when the plug-in is being registered on a 64 bit operating system:
HKEY_LOCAL_MACHINE
SOFTWARE
WOW6432Node
MimarSinan
InstallAware
2.0
Plug-Ins
{Plug-In Name}
(Default) = {Full Path to Plug-In Design-Time/Compile-Time DLL}
Action = {Plug-In Name}
Execute = {File Name (without path) to Plug-In Run-Time DLL}
Script = {Plug-In Script Display}
SupportsDownloads = {DWORD}
DefaultState = {Plug-In Download Handler Default State}
StateDescription = {Plug-In Download Handler State Description}
Plug-In Name
The name of the plug-in. This will also be used for displaying the plug-in command on the commands list.
Plug-In Script Display
The text that will be displayed in the script editor when a plug-in command has been added into the script.
DWORD
This optional value may be recorded only by plug-ins that are designed to handle internal setup engine downloads for Web Media Blocks. Set this 32 bit integer DWORD value to 1 if your plug-in is designed to handle such downloads.
Any other value (or omission of this value) indicates that the plug-in does not support internal setup engine downloads (as would be the case for typical plug-ins performing non-download related tasks).
Plug-In Download Handler Default State
This optional value may be recorded only by plug-ins that are designed to handle internal setup engine downloads for Web Media Blocks.
Set this value to the default state string the plug-in should suggest while being selected as a download handler through the Use Download Engine command.
Plug-In Download Handler State Description
This optional value may be recorded only by plug-ins that are designed to handle internal setup engine downloads for Web Media Blocks.
The Use Download Engine command will display this string as a hint for the meaning of the plug-in state string. If this value is not recorded, the Use Download Engine command will suggest to review the plug-in documentation.
Unicode Support
Plug-in DLLs may implement the functions they export as Unicode, ANSI, or both.
If both implementations are available, Unicode versions of InstallAware will always use the Unicode implementations, and non-Unicode versions of InstallAware will always use the ANSI implementations.
If only ANSI implementations are available, the plug-ins will work with all versions of InstallAware. However, while running under Unicode InstallAware versions, any Unicode data passed to plug-ins in script variables may be partially or completely corrupted, if the data stored does not have an ANSI representation.
If only Unicode implementations are available, the plug-ins will only work with Unicode versions of InstallAware.
Mandatory Unicode for Optional Enhancements
The only exception to the above rule are functions (and callbacks) handling internal setup engine downloads and receiving project code signing settings, which must always be Unicode only.