The \SuperProNet Combo Installer\Merge Modules folder on the CD contains the merge modules of the Sentinel System Driver, SuperPro Server and Monitoring Tool that can be integrated seamlessly into your application's installation routines. The merge modules themselves contain the necessary files and registry entries, hence freeing you from the burdensome task of doing them manually. You can associate a merge module with a particular feature to allow the end user to accept or reject it. Alternatively, you can make it a required item so that the end user has to install it with your application.
Adding the merge modules to your installer is relatively straightforward, but there are a few items that must be placed in your installer in the right sequence to make it all work. There are a few custom actions as well that are discussed below to perform the installation.
This section elaborates on integrating the SuperPro merge modules.
The installation is broken up into five merge modules described below to allow you to control which component gets installed on your end user's system.
This module contains the configuration program and its required components. This module must be installed with the driver regardless of which driver you install (parallel or USB).
This module contains the driver for any of the Rainbow Technologies parallel port keys. Installation of this driver is optionalonly necessary to support the parallel port key use. However, any application that uses a USB SuperPro key and was not compiled with the SuperPro 6.1 or later libraries must have the parallel driver installed. Otherwise, the application will not be able to talk directly to the USB driver. This driver is safe to install on systems that lack a parallel port.
This module contains the USB SuperPro driver. Installation of this driver is optional and, can be installed alone if the application that uses the USB SuperPro key was compiled with the SuperPro 6.1 or later libraries. Otherwise, the parallel driver should also be installed along.
This module contains the SuperPro server. The module intuitively installs the relevant binaryspnsrv9x.exe on Windows 9X and spnsrvnt.exe on Windows NTbased on the operating system the system is running on.
This module contains the SuperPro Monitoring Tool
Note: The merge modules are written and tested with InstallShield Developer 7.0.4.
Some of the necessary steps to install a component are performed as "custom actions" within the merge modules. Since the merge module itself contains the custom actions that are to be merely added to the sequence table of the installer and hence you need not make any custom action on your own.
Every Windows Installer package has a sequence table consisting of a sequence number against each action. The actions are executed in the ascending orderfrom lowest to highest. You will then manually add the merge module custom actions in the specified order to your sequence table. See the topic "Sample Use of Merge Modules" for more information.
When a merge module is added to an installation package, the custom actions are referred to by their names and the GUID (global unique identifier) of the merge module. The GUID can be found by right clicking on the file from Windows Explorer, selecting Properties and looking for the file's revision number. An example name for the RemoveOldDriver action would be:
RemoveOldDriver.B391C189_6953_11D4_82CB_00D0B72E1DB9
Each action listed in the sequence table has a condition field that will allow you to define when the action should be performed. It is important that this field be filled out correctly since you may not always need or want to carry out a particular custom action.
For more information on action, custom actions, conditions, and the sequence table refer to the Windows Installer on the Microsoft's MSDN Web site.
The following table describes what customs actions need to be added to your installation package sequence table. It also shows where in the table it should be inserted and the recommended condition that should be used to run this action. All conditions are case sensitive.
Note: There are no custom actions required for the SuperPro Monitoring Tool merge module. The table below only shows the custom actions meant for the Sentinel System Driver and SuperPro server.
Custom Action Name | Use |
---|---|
RemoveOldDriver | Inserted After Standard Action:
Recommended Condition:
Description: This custom action can be used to both remove any previous version of the Sentinel System Driver prior to 5.39, and it can be used to determine if an older version exists. This action uses properties to pass information back and forth and can be used to determine what course of action needs to be taken by the installer. This action should be used on both the user interface and install execute sequences. The action always checks the currently installed driver version to decide how to proceed. Depending on the version it detects, the following properties will be set:
After determining whether an old driver is installed, the action will only proceed to remove the older version if the property CONFIRMUPGRADE is set. If this property is not set, the action exits. In this way, the action can be called twicethe first time to determine if an older version is installed, the second time to actually remove the older driver version. This allows you to confirm with users whether or not they would like to proceed. The supplied installer is a good example of calling this twice, it calls it the first time without the CONFIRMUPGRADE property set. If an old driver is found, it presents the user with and upgrade confirmation screen. If the user accepts, it calls the custom action again with CONFIRMUPGRADE set to actually uninstall the old version. If the action actually removes an older driver, it will set the OLDDRIVERREMOVED property. This property can be used later to determine if a reboot is required. Most often, the old driver can be removed without any problems. If the user has some of the driver files locked, the files will be flagged for deletion upon rebooting the system. If this is the case, the action will set the property REMOVEOLDDRIVERREBOOT. If this property is set after returning from calling this action, you should reboot immediately and then continue the installation. If there is no driver installed, this action does nothing and is therefore safe to run in any situation. This action should be inserted before the CostInitialize standard action. |
RemoveOldDriverAgain | Inserted After Standard Action:
Recommended Condition:
Description: This action is exactly the same as RemoveOldDriver. A custom action can only be inserted into a sequence table once. The RemoveOldDriver function can be called twice, however, by using the RemoveOldDriver and the RemoveOldDriverAgain custom actions. If the action is called without setting the CONFIRMUPGRADE property, it will only report if an old driver is installed via the OLDDRIVERFOUND property. This custom action is identical to the RemoveOldDriver custom action, but is included to allow you to perform this function twice. A good example of using these custom actions is calling RemoveOldDriver to confirm via the GUI whether the user wants to upgrade the driver. After the user confirms the upgrade, you set the CONFIRMUPGRADE property and call RemoveOldDriverAgain to actually do the uninstall. Do NOT install the new driver without successfully removing the old driver first! |
stopservers | Inserted After Standard Action:
Recommended Condition:
Description: This custom action is used for stopping the SuperPro servers on Windows. |
RemoveVDDRegEntry | Inserted After Standard Action:
Note: If the stopservers custom action is used, then RemoveVDDRegEntry must follow it. Recommended Condition:
Description: This custom action will remove the registry entry for the NT virtual device driver (VDD) during uninstallation. Since this registry entry may contain other pieces of information, it cannot simply be deleted. There is no effect if the VDD is not installed and this action is called. This action should be added in Windows NT/2000/XP as noted in the conditions. This action should be inserted after all other registry values are removed in the installation process. |
MakeVDDRegEntry | Inserted After Standard Action:
Recommended Condition:
Description: This custom action will add a registry entry for the NT virtual device driver (VDD). Since this registry entry may contain other pieces of information, it cannot be simply added or overwritten, but must be modified by this custom action. The VDD component is not installed if the property NOVDDINSTALL is added to the command line. For this reason, this action should also not be called if this property is set. This is reflected in the recommended condition. This action should only be added in Windows NT/2000/XP as noted in the conditions. This action should be inserted after all other registry values are added in the installation process. |
InstallNTParService | Inserted After Standard Action:
Recommended Condition:
Description: This custom action adds the NT parallel driver service to the service control manager. Since this is a kernel service, it must be added via a custom action. This should only be installed if the parallel driver is being installed. ParDriver in the recommended condition is the name you give the parallel driver feature in your installer. If you are always going to install the parallel port driver, you can leave this item out of the conditions. For example, the supplied installer uses the condition "VersionNT and &Parallel_Driver=3." This action should only be performed on Windows NT/2000/XP as noted in the conditions. This action should be performed after all other services are added during the installation process. |
StartParallelDriver | Inserted After Standard Action:
Recommended Condition:
Description: This custom action will start up the parallel driver so that any application can use it. In many cases, the driver can be started up without requiring a reboot. However, in certain instances a reboot is required to start up the driver. If a reboot is required, it automatically flags the installer to reboot upon completion. Also, the custom action will set the SSDREBOOTREQUIRED property to the installer. The action should only be called if the parallel driver is being installed. ParDriver in the recommended condition is the name you give the parallel driver feature in your installer. If you are always going to install the parallel driver, you can leave this item out of the conditions. For example, the supplied installer uses the condition "&Parallel_Driver=3". This action should be run for every operating system, the action will detect the OS and determine the proper course of action for that OS to start the driver. This action should occur at the end of the installation process after all other files are installed. |
CopyUSBINF | Inserted After Standard Action:
Recommended Condition:
Description: This custom action tells Windows 2000/XP where to find the "INF" file for the USB SuperPro. Effectively, this step pre-installs the driver so that when the user plugs in a USB key for the first time, Plug 'n' Play can finish the installation without any user response. This should only be called if the USB driver is being installed. USBDriver in the recommended condition is the name you give the USB driver feature in your installer. If you are always going to install this driver, you can leave this item out of the conditions. By default, the USB driver files are installed in C:\Program Files\Rainbow Technologies\Sentinel System Driver. If you install the files in a different location, you can set the SYSDRIVERDIR property to the path of the files. The custom action will use the directory in the property to find the files. Although PnP is supposed to be able to update the driver without rebooting, in some cases this is not possible. If a reboot is required, it automatically flags the installer to reboot upon completion. Also, the custom action will set the SSDREBOOTREQUIRED property to the installer. This action should only be performed on Windows 2000/XP (Windows NT 4.0 does not support USB), as noted in the conditions. All files have to be copied to the local system before this action can be completed, therefore this should always be run last in your installation. |
StartSpService | This custom action restarts the SuperPro server/service after
installing the Sentinel system Driver. Recommended Condition:
|
The Sentinel System Driver contains a configuration program called SetupSysDriver.exe. It allows the end user to configure the driver if necessary. It also contains a button that allows the user to call the original installer to modify, repair, or remove the installation.
By default, to call up the Sentinel System Driver installer, the program uses the product code GUID (Global Unique Identifier) for the installer contained within the driver. If you are using merge modules, then the product code GUID will be a different value. The configuration program will not be able to call up the installer.
You can link the configuration program to your own installer by placing the product code GUID in a file. Alternatively, you can disable this feature so that the end user must go through your own software. To do this, create a file called sysdriver.guid and place it in the same directory as SetupSysDriver.exe. This file must reside in the same directory as the executable. The first line of the file should contain the product code GUID of your installer. Only the first line of the file is read. The GUID must be the only item on the first line and be in the following format:
{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
For example the Combo Installer GUID is:
{1E556F64-5F1A-40AA-9A32-17DFECA6E16E}
If the value given is not a valid GUID as above, it will be rejected and the hard-coded value will be used instead. If you put in the word "disable" instead of a GUID, the installer will disable this feature and not let the user call any installer from the configuration program.
The supplied installer for the Combo Installer installs via the merge modules. It has to perform all the steps listed for sequencing the custom actions in order to properly install. For that reason, it is a good example of how to add the same custom actions into your own installer via the merge modules.
Below is the sequence and conditions given for each custom action used by the installer. This information is provided as an exampleyour actual conditions and sequence numbers may be different depending on your circumstances. Also listed are some standard actions to illustrate how the custom actions fit relative to standard actions.
Action | Sequence Number | Condition |
---|---|---|
RemoveOldDriver | 72 | (none) |
UpgradeConfirmation (Dialog) | 75 | OLDDRIVERFOUND and not AFTERREBOOT and not OLDDRIVERREMOVED |
RemoveOldDriverAgain | 84 | OLDDRIVERFOUND and not AFTERREBOOT and not OLDDRIVERREMOVED |
MustReboot (Dialog) | 94 | REMOVEOLDDRIVERREBOOT and not AFTERREBOOT |
NewDriverFound (Dialog) | 97 | NEWDRIVERFOUND |
SetupInitialization (Dialog) | 100 | (none) |
The installer warns the user before upgrading to a new version of the Sentinel System Driver. It accomplishes this by first calling the RemoveOldDriver custom action. If an old version is found, the OLDDRIVERFOUND property is set. This property is used to determine if the UpgradeConfirmation dialog should be shown.
If the user accepts the upgrade, the CONFIRMUPGRADE property is set and RemoveOldDriverAgain is called. This time the driver is actually removed and the OLDDRIVERREMOVED property is set.
The MustReboot Dialog tells the user to reboot in order to continue (always a possibility when uninstalling, but this happens very seldom in practice).
Also, the NewDriverFound dialog is presented to the user if a newer version is already installed. This dialog does not allow the user to continue since there is no point in installing a version older than the installed version.
After all this is done, the installer continues onto the SetupInitialization dialog as usual.
Action | Sequence Number | Condition |
---|---|---|
RemoveOldDriver | 150 | not OLDDRIVERREMOVED and UILevel<4 |
OldDriverError | 170 | OLDDRIVERFOUND and not OLDDRIVERREMOVED |
NewDriverError | 180 | NEWDRIVERFOUND |
SetSysDriverDir | 190 | (none) |
ValidateProductID* | 300 | (none) |
. | ||
UnregisterClassInfo* | 1350 | (none) |
stopservers | 1360 | REMOVE |
RemoveVDDRegEntry | 1375 | VersionNT and &Parallel_Driver=2 |
UnregisterExtensionInfo* | 1400 | |
. | ||
WriteRegistryValues* | 2400 | (none) |
MakeVDDRegEntry | 2425 | VersionNT and not NOVDDINSTALL and &Parallel_Driver=3 |
WriteINIValues* | 2450 | (none) |
. | ||
InstallServices* | 2750 | VersionNT |
InstallNTParService | 2775 | VersionNT and &Parallel_Driver=3 |
StartServices* | 2800 | VersionNT |
. | ||
PublishProduct* | 3100 | |
ScheduleReboot* | 3150 | Version9X and (REMOVE or REINSTALL) |
InstallFinalize* | 3200 | (none) |
StartParallelDriver | 3250 | &Parallel_Driver=3 |
CopyUSBInf | 3300 | VersionNT and &USB_Driver=3 |
RemoveExistingProducts* | 3500 | (none) |
* denotes a standard Windows Installer action. This is inserted to show relative placement of custom actions to standard actions.
RemovedOldDriver is called first to uninstall and existing versions of the Sentinel System Driver before continuing. It is important to note that if the installer is told to install quietly, the user interface is completely skipped, so this custom action needs to exist in both sequence tables. This action gets called when the installer has been told to run in a quiet mode. The OldDriverError causes the installer to exit because an older version exists and has yet to be removed. This is a catch-all error condition to be sure we don't proceed to install this version without uninstalling an old version.
Similarly, NewDriverError causes the installer to exit if a newer version of the driver is already installed. Then SetSysDriverDir sets the property SYSDRIVERDIR to the directory that the driver will be installed to.
OldDriverError and NewDriverError are basic type 19 error custom actions. SetSysDriverDir is a basic type 51 property assignment custom action. These custom actions are defined in the Windows installer; see the Microsoft MSDN for details on these custom actions.
RemoveVDDRegEntry and MakeVDDRegEntry modify the system registry and therefore should take place in the same area that the installer adds and removes registry entries. The conditions should cause the registry entry to be added during install and removed during uninstall.
The parallel driver on Windows NT/2000/XP systems is a kernel mode service. Windows Installer will not add kernel mode services via its normal method, so the custom action InstallNTParService is added to add the service to the system. It should be called when Windows Installer adds other services during its own InstallServices action.
The StartParallelDriver and CopyUSBINF action have to occur at the end of the installation sequence when all the files are copied, services created, etc. Thus they should exist at the very end after the InstallFinalize action.
The instructions given below explain changing the destination path of the various merge modules:
In some cases, during the processing of a custom action, it is determined that a reboot is necessary to complete the installation. If this occurs, the custom action will set the property SSDREBOOTREQUIRED. The custom action will also automatically flag the installer to reboot after installation is completed. The exception to this is the RemoveOldDriver custom action. In the rare case that this custom action needs to reboot, the reboot needs to be immediate before the installation can continue. If that condition is met, it will set the property REMOVEOLDDRIVERREBOOT property. It will not set the SSDREBOOTREQUIRED property.
The parallel port driver on Windows 95/98/ME systems is not unloaded from memory until the next reboot after being uninstalled. Thus, it is recommended you reboot after uninstallation on these systems, although this is not required. If the driver is left in memory after uninstallation, it will be removed during the user's next shutdown or reboot.