Sentinel System Driver Windows Installer Merge Modules

 

Version 5.39 and later of the Sentinel System Driver contains a new installation method using the Windows Installer provided with Windows 2000. The full installer contained in this release was made from the three merge modules contained in the \Merge Modules directory. The installer that you run is essentially a front-end to the merge modules that contain the actual information necessary to install the driver.

Since the Windows Installer only supports Windows 95, 98, ME, Windows NT 4.0 SP 3 and higher and Windows 2000, the merge modules only contain the drivers for those operating systems. The merge modules can be added to any Windows Installer package to seamlessly add the Sentinel System Driver installation to your application.

Adding the driver 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. This method is described for users who wish to merge the driver installation into their own installer. Another alternative is to call the driver installation (setup.exe) from your own installer. Using the right command-line options, you can fully control what components are installed, and whether the user can interact with the installer. More information on this is contained in Installation Options.

Note: The merge modules were written using InstallShield for Windows Installer version 2.03, and were tested with Windows Installer versions 1.1 and 1.2. If using Wise for Windows Installer, see Special Instructions for Adding Custom Actions to Wise Windows Installer.

 

Organization of the Merge Modules

The installation is broken up into three merge modules to allow you to control which driver gets installed on the end user's system. (Note that these file names changed for the 5.39.2 release.) The three files are:

SSDConfigfiles.msm

This module contains the configuration program and its required components. It also contains the readme and help files. This module must be installed with the driver regardless of which driver you install (parallel or USB).

SSDParallel.msm

This module contains the driver for any of the Rainbow Technologies parallel port keys. Installation of this driver is optional; it is only necessary to support 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 cannot talk directly to the USB driver. This driver is safe to install on systems that lack a parallel port.

SSDUSB.msm

This module contains the USB SuperPro driver. Installation of this driver is optional. This driver can be installed alone if the application that uses the USB SuperPro was compiled with the SuperPro 6.1 or later libraries. Otherwise, this driver should be installed along with the parallel driver.

 

Merging the Driver into Your Installer

The driver merge modules can be added to any Microsoft Windows Installer package. There are many third-party applications that can be used to design a Windows Installer package. An example would be "InstallShield for Windows Installer." As do other such applications, InstallShield assists you in building the actual installation media and simplifies configuration. For more information about using and developing a Windows Installer package, visit Microsoft's MSDN Web site.

Once you can add the merge module to your installation package, you can associate it with a particular feature of the installation. This will allow the end user to have some control of whether this feature should be installed. Alternatively, you can make it a required item so that the end user has to install it with your application.

The merge module itself contains the necessary files and registry entries to install the driver. It will determine what needs to be installed based on the operating system it is being installed on. This frees you from having to understand exactly how to install the driver. There are a few custom actions that have to be performed to complete the driver installation and they are described below.

 

Adding a Custom Action to Your Installation Package

Some of the necessary steps to install the driver are performed as "custom actions" within the merge modules. While the merge module contains the custom action itself so you do not have to do any coding, the action has to be added to the sequence table of the installer. Every Windows Installer package has a sequence table that identifies what steps need to be performed in what order. You will have to manually add the merge modules custom action to your sequence table.

When a merge module is added to an installation package, the custom actions from the merge module are referred to by their action's name and the GUID (global unique identifier) of the merge module. Each merge module has its own GUID that 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

Most third-party software packages take care of this, putting this name together for you and presenting you with a list of all the custom actions from the merge modules. Most Express or Lite installer packages cannot perform the necessary sequencing to use these merge models. (And, see Special Instructions for Adding Custom Actions to Wise Windows Installer for sequencing instructions when using that installer.)

The actions are then placed in the sequence table of the installation package. Each action in the sequence table is given a sequence number. The actions are carried out from the lowest sequence number to the highest. Many third-party packages will list the actions in order and automatically assign a sequence number that inserts the action in the desired place. Otherwise, find the sequence number of the action you would like your action to take place after and assign it a number higher. For example, I want to place the RemoveOldDriver custom action after the RemoveFolders action. The RemoveFolders sequence number is 1800, so I assign the RemoveOldDriver sequence number 1825 (most actions are separated by a value of 50). The installer then knows to perform this action after it has completed the RemoveFolders action.

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 Microsoft's MSDN Web site.

 

Required Custom Actions

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.

Custom Action Name Use
RemoveOldDriver

Inserted after Standard Action:

  • This custom action should be inserted before CostInitialize.

Recommended Condition:

  • None required.

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:

  • OLDDRIVERFOUND - If a previous version is installed, this property will be set depending on if the driver is found. The older driver has to be removed before installing this version.

  • NEWDRIVERFOUND - If a driver newer than this version is found, this property will be set. If this property is set after running RemoveOldDriver, you should abort the installation.

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 twice—the 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:

  • This custom action should be inserted before CostInitialize.

Recommended Condition:

  • OLDDRIVERFOUND

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!
RemoveVDDRegEntry

Inserted After Standard Action:

  • RemoveRegistryValues

Recommended Condition:

  • VersionNT and REMOVE

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 only be added in Windows NT or 2000 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:

  • WriteRegistryValues

Recommended Condition:

  • VersionNT and not NOVDDINSTALL
    and not REMOVE

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 or 2000 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:

  • InstallServices

Recommended Condition:

  • VersionNT and &ParDriver=3

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 or 2000 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:

  • InstallFinalize

Recommended Condition:

  • &ParDriver=3

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:

  • InstallFinalize

Recommended Condition:

  • VersionNT>=500 and &USBDriver=3

Description:

This custom action tells Windows 2000 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 (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.

 

Linking the Configuration Program to Your Installer

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 Sentinel System Driver GUID for version 5.39 is:

{791CAF6C-90A3-11D4-8306-00D0B72E1DB9}

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.

 

Special Instructions for Adding Custom Actions to Wise for Windows Installer

Because InstallShield and Wise handle sequencing actions in a different manner, using the Wise for Windows installer with the Rainbow merge modules requires a slightly different approach. Wise expects you to sequence a custom action from a merge module at the merge module design time (i.e., sequencing information is stored in the merge module). InstallShield expects you to sequence the merge module at the installer design time (no sequencing information is kept in the merge module, so the installer has to specifically sequence it).

Since the merge modules distributed with the Sentinel System Driver are made with InstallShield for Windows Installer, they do not have sequencing information stored in them. Wise for Windows Installer therefore can't automatically sequence the actions as it normally would because the information does not yet exist.

You can manually sequence the custom actions in Wise for Windows Installer by doing the following:

  1. Open your Wise for Windows Installer project (you must open it up from an .msi file, not a .wsi file).

  2. Go to the Setup Editor and select the Tables view.

  3. Find the CustomAction table. Look for your desired custom action in the list that you would like to sequence (this assumes you have already added the merge modules to your project). You will see the name as it is listed in the driver documentation with "GUID" attached to it.

  4. Select the action and then copy the name to the clipboard by right clicking on it and selecting copy.

  5. Next, go to the desired sequence table you want to add the custom action to. Normally, it will be either the InstallUISequence or the InstallExecuteSequence table.

  6. Identify the action you would like to sequence this after and note its sequence numbers. For example, the InstallServices action is normally sequence number 5800 in Wise.

  7. Right click on the table and select New Row.

  8. In the empty row, copy the name of the custom action under the Action column.

  9. In the Condition column, insert the proper condition based on the driver documentation.

  10. Finally, in the Sequence column, enter a value that is higher than the action you would like it sequenced after. For example, the InstallNTParallelDriver custom action should be sequenced after the InstallServices action. Since the InstallServices action is sequence number 5800, you might sequence InstallNTParallelDriver using value 5810.

  11. Repeat this for all the custom actions listed in the documentation.

 

Sample Use of Merge Modules

The supplied installer for the Sentinel System Driver 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 example—your 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.

The Install User Interface Sequence Table

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.

The Install Execute Sequence Table

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)
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 NT and Windows 2000 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.

 

Rebooting the System

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.