Extending Active Setup

Nancy Winnick Cluts
Developer Technology Engineer
Microsoft Corporation

Last updated: November 3, 1997
(links to latest documentation added in Introduction)

Changes for the Internet Explorer 4.0 Final Release

• The explanation of the FTP download process was updated.
  
  
• The download page screen shot was updated.
  
  
• The RegCheck control was rewritten in ATL (it was originally written in MFC).
  
  
• The IsComponentInstalled method now also has the possible return value of 3.
  
  
• The OLE Automation Interface and events for VBScript was updated to reflect changes in flags, options, and additional events and methods.
  
  
• The CIF file documentation was updated to reflect new names, flags, and options.

Introduction

When the team that creates the Internet Client SDK (see online documentation at http://www.microsoft.com/msdn/sdk/inetsdk/asetup/default.asp) needed a setup utility, they decided to take advantage of Active Setup. Active Setup is included in Internet Explorer 4.0 and provides generic setup technologies for control developers. This article explains what Active Setup is, what utilities it provides, and why and how the SDK team extended it. Active Setup documentation can be found in the Internet Explorer Administration Kit (http://www.microsoft.com/ie/ieak/). Detailed information about Active Setup can also be found in the Internet Explorer Deployment Guide, which is available on the Web at http://www.microsoft.com/ie/corp/default.htm?/ie/corp/deployguide.htm. It is also important to bear in mind that this article describes just one use of Active Setup and one solution that employs this technology—there is always more than one way to peel a potato (as a cat-lover, I cannot use that other colloquialism).

What Is Active Setup?

Active Setup is a group of technologies designed to componentize your application's setup and make future client updates smaller and easier. To use Active Setup, you create:

• A digitally signed cabinet (.CAB) file containing the bits you’d like to ship to your customers.
  
  
• An information (.INF) file or self-extracting executable (.EXE) file that tells Active Setup what files to install and where.
  
  
• A Component Install File (.CIF) that tells Active Setup all other details about the installation.

Active Setup ensures that only those components that need to be downloaded get downloaded (how many times do you want to download the Visual Basic® 5.0 DLL?) and gives you the opportunity to specify whether you will to prompt the user to skip files.

If a user is running Internet Explorer 4.0 Preview 2, another bonus everyone gets with Active Setup is smart recovery from a failed download session over the Internet. Just like you, I’ve spent too much time downloading a component only to have my connection dropped. I'm then left wondering what was left to download, what I can safely remove, or even if I could use the previous version of the component (which can be a real problem if you’ve downloaded a new executable without getting all of the new DLLs that you need). From pages that use Active Setup, such as the Internet Client SDK page, users are prompted with a list of installed items and will know to not download those items again.

Programming Interface Overview

Active Setup consists of two ActiveX™ controls that support the implementation of Internet-based component setup. These controls are INSENG.DLL, which contains the COM interface, and ASCTRLS.OCX, which contains an OLE Automation interface that can be used to talk to INSENG.DLL and enables you to display simple text dynamically on a Web page. The sections below describe the OLE Automation interface for Active Setup and the events supported through Visual Basic Scripting Edition (VBScript). These sections will give you an idea of what is supported by Active Setup. It is not final documentation—you'll need to refer to the Internet Client SDK for the scintillating details and updates.

OLE Automation interface for Active Setup

The following methods are supported by Active Setup for Internet Explorer 4.0:

Abort

This method stops the current download and installation session.

BaseURL

This method sets a base URL root that can retrieve packages from Internet sites. This URL can be FILE-, FTP-, or HTTP-based. You cannot use this method when the EngineStatus is 2 (installation is in session).

EngineStatus

This method is used to determine whether the engine is ready for other methods to be called or to inform the user that an operation has failed. The possible return codes are:

0 — The engine is not ready. No .CIF file is loaded.
1 — The engine is downloading the .CIF file.
2 — Installation is in session.
3 — The engine is ready.

FinalizeInstall

This method is used at the end of an installation process to reboot the machine (if needed) for the newly installed components to operate correctly. It takes two flags:

0 — Do not reboot.
2 — The user interface should not prompt the user to reboot.

The default is to reboot via a user prompt.

IsComponentInstalled

This method displays the installation and component status to the user. It checks the Registry keys under HKEY_LOCAL_MACHINE\Software\Microsoft\ActiveSetup to determine the installation state and version. The method takes one argument, the Component ID, and returns:

0 — The component is not installed.
1 — The component has already been installed.
2 — The component is installed but a newer version is available for download.

ProcessComponents

This method processes the components in the .CAB file and can direct Active Setup to delay a reboot, to not show the progress of the installation, or to not show an end summary to the user.

ReadyState

This method is used to determine if the control is ready to accept VBScript. It returns:

0 — The control is not ready.
4 — The control is ready.

SetAction

This method is used to queue up components Active Setup should install. You give it the ID of the component and define an action. Possible actions include:

0 — Skip installation of the component.
1 — Install the component.
2 — Uninstall the component.

You cannot call SetAction during EngineStatus 2 (installation is in session). This method returns 0 if it succeeds.

SetCIFFile

This method sets the .CIF file for a specified .CAB file. It cannot be called during a download or installation session. The .CIF file can also be set via HTML properties for the INSENG.DLL in the Web page. This method can be called when the EngineStatus method returns 3 (Engine ready).

Size

Returns size of a component in kilobytes based on values from the .CIF file and a multiplier.

TotalDependencySize

This method returns the dependency size in kilobytes based on .CIF-data total download size for all components the SetAction method queued up to install in the engine.

TotalDownloadSize

This method returns the total download size in KB based on .CIF-data total download size for all components the SetAction queued up to install in the engine.

Events for VBScript

The following VBScript events are supported by Active Setup for Internet Explorer 4.0 Preview 2:

InstallEngine1_OnReadyStateChange — This event returns:

0 — The control is not ready.
4 — The control is ready.

This event is the same as the ReadyState method.

InstallEngine1_OnEngineStatusChange — This event is equivalent to the EngineStatus method described in the previous section.

InstallEngine1_OnStartInstall — This event returns the total size of the installation when the installation session starts.

InstallEngine1_OnStopInstall — When the installation session is finished, this event is fired and the result can be:

0 — Success.
1 — Failure.
2 — A reboot is necessary.

InstallEngine1_OnStartComponent — This event returns the component’s ID, the total size of the component, and the friendly name of the component as indicated in the .CIF file.

InstallEngine1_OnStopComponent — This event returns the component’s ID, the result (0 for success or 1 for failure), the phase the component was in when it was stopped, the friendly name of the component as indicated in the .CIF file, and whether a reboot is required.

The Component Install File

The Component Install File (.CIF) is used by Active Setup to determine what to install and how to install it. The following table describes version 1.2 of the .CIF file format. It is correct as this article is being written, but check the final Internet Explorer 4.0 documentation in the Internet Client SDK for the final format. An example of a .CIF file follows this table.

The following is an example of a .CIF file that might be used to install Internet Explorer 4.0 Preview 2:

[BASEIE40_Win]
DisplayName="Microsoft Internet Explorer 4.0"
Size=8300,0
GUID={89820200-ECBD-11cf-8B85-00AA005B4383}
URL1="Setupw95.cab",3
URL2="ie4_s1.cab",7
URL3="ie4_s2.cab",7
URL4="ie4_s3.cab",7
URL5="ie4_s4.cab",7
; URL6="ie4_s5.cab",7
Command1="ieclean.inf"
Type1=0
Command2="Setup.exe"
Switches2="/QT /gc c:\nashlog.txt"
Type2=2
Version=4,71,TOK_BUILDNUM,TOK_CIFNUM
;UninstallKey="IE40"
Reboot=1
InstalledSize=2800,19300
SuccessKey="IE40,%UNQUOTED_APPVERSION_CDROM%"

The [ITEM] is the identifier for Internet Explorer 4.0, while the DisplayName is set to the friendly name. There are four cabinet files (note that one is commented out) and the IECLEAN.INF file is run after all of the .CAB files have been downloaded.

Why the SDK Team Uses Active Setup

The Internet Client SDK team works on a very aggressive schedule. The audience for the SDK has changed dramatically in recent years (okay, really months, but technology is moving very rapidly). Previous to this SDK, the people downloading an SDK were independent software vendors (ISVs) or independent hardware vendors (IHVs). To support all the new development on the Internet, the INet SDK team needs to provide information for independent content providers (ICPs) and HTML authors as well. An SDK is no longer a tool just for propeller heads like me; the team needs to serve an audience that includes first-time HTML authors and hard-core C++ or Java™ developers.

Another issue for the SDK team is the sheer size of the SDK. It has become huge, and it is obvious that most people would rather download selected portions of the SDK than download the full SDK. For example, a Web developer creating HTML-based content for the Web probably doesn't want to burn up disk space with user-interface C-based programming information.

The SDK team decided to fix this problem by “chunking” up the download into bite-sized pieces. By chunking up the SDK, the .CAB files become smaller, which translates into shorter download times for the user. This has proved to be a good decision and the team intends to go back and refine their chunking further, to remove redundancies and provide greater granularity.

Another bonus that chunking up the SDK provides is the ability to update only the .CAB files that need updating. This means that the user no longer needs to download the entire SDK to get the updated portions. This also means that the team can add technologies more easily without requiring the user to download items she already has. And because Active Setup enables you to keep track of what is installed and where, the SDK team can also make updates more easily (remove what’s no longer needed and leave intact whatever didn’t change).

Finally, because Active Setup is new for Internet Explorer 4.0, the SDK team can exploit the new technologies contained in Internet Explorer 4.0 and look into some of its other new features, like channels.

Now, I don’t want you to think that using Active Setup is the only solution to the problems that the SDK team was having. That’s certainly not the case. In order to solve these problems, the team could have decided on any one of the following solutions:

• Use Active Server pages that query the user for which components to install and dynamically create a page with code-download tags for various controls the user wants to install. This solution doesn't scale perfectly, but it can work.
  
  
• Write a Visual Basic control that calls into the ActiveX APIs to do work similar to the ASP solution mentioned above.
  
  
• Write a plug-in that provides the same functionality. The plus side to this solution is that it would work in Netscape Navigator.

An issue to consider

Now let’s talk about some issues the team needed to consider when deciding whether to use Active Setup. The biggest issue was that Active Setup requires the support of ActiveX from the browser. This means that anyone who wants to use the new setup program needs to run a browser that supports ActiveX controls. Because the Internet Client SDK is designed for people who want to develop for Internet Explorer 4.0, the team decided that it made sense to use the technology. They also decided to set up a special FTP site for customers who want to download the SDK but are not running a browser that supports ActiveX.

The Decision to Extend Active Setup

Now that you‘ve decided to use Active Setup, why would you want to extend it? Active Setup is a great set of technologies but it isn’t perfect for all installations. The good news is that you can extend it to meet your needs. That’s just what the SDK team did.

One issue the SDK team solved was that Active Setup assumes that all files are installed in the same directory. In the early beta versions of Internet Explorer 4.0, there is no way to specify different directories for different components. Because a user of the SDK might want to install the C/C++ tools as well as the Java tools, that user might also want to put these files in different places on her system.

The SDK team also has to deal with license agreements. Depending on what components a user decides to download, she should be prompted with the appropriate license agreement. You wouldn’t want to be prompted for the Java license if you aren’t downloading it—that would be confusing!

The extended Active Setup

Now that we know why the SDK team decided to extend Active Setup, let’s look at how they did it. But first, here's what the installation page for the Internet Client SDK looks like:

Figure 1. Installation page for the Internet Client SDK

As you can see from Figure 1, the user can choose what to download based on her interests. She is also shown the size of the components, an estimate of the time it will take to download the items, and whether the items are currently installed.

The extension of Active Setup was done with a 32-bit ActiveX control called REGCHECK.OCX. This control was written using Microsoft® Foundation Classes (MFC) 4.2b and handles all of the selective downloading of the .CAB files for the SDK. To run the control, the team needed to download the .OCX, as well as MSVCRT.DLL, MFC42.DLL, and OLEPRO32.DLL, if those files did not already exist on the client machine. The team also needed to digitally sign the control so that Active Setup would download the .CAB file.

The control uses a file, HEADGRPH.HTM, in the \help directory of the SDK to store the current download information. This file currently contains a single .GIF. In the future, this file will also include a <SCRIPT></SCRIPT> tagset with information about the current status of document files on the user's machine. The <SCRIPT> tagset will have the following format:

<script>
var comp=new Array(5);
comp[0]="n";
comp[1]="n";
comp[2]="n";
comp[3]="n";
comp[4]="n";
</script>

The control exposes a single Status method that does the following:

1. Verifies that HEADGRPH.HTM exists (that is, was installed correctly) by attempting to open it.
   
   
2. Verifies that the <SCRIPT>/</SCRIPT> tags appear in the file.
   
   
3. Verifies that the comp[n]… entries appear in the file.
   
   
4. Opens the registry.
   
   
5. Queries the registry for the GUID corresponding to each .CAB containing documentation files.
   
   
6. Records the status for each GUID/file.
   
   
7. Closes the registry.
   
   
8. Maps GUID/file status to entries in the script.
   
   
9. Closes HEADGRPH.HTM.

How it all works

Aside from the control, the SDK team created some extensive scripting (with VBScript and Jscript™) to extend Active Setup. (Did I use the word "extend" enough for you yet?) When you go to the download page for the SDK, note that there are check boxes that you can check to designate which items you would like to download. If you view the source for the page, you’ll see pages of scripting. Within the source, you'll see that the script checks the buttons (those check boxes) to find out which are marked as already installed and which the user has chosen to download. Then when the user chooses to install (to process), the SDK will download only the .CABs that are marked.

Sub CheckBoxEventHandler( CheckBox, CheckBoxName, LongName, default )

   ' CheckBox is the Form Element.
   ' CheckBoxName is the name of the entry ( a string ).
   ' LongName is a descriptive name ( a string ).
   ' default is a bool indicating the default state of the checkbox.

   dim installed         ' Has this item been installed before?
   dim answer            ' Should we reinstall the code?

   dim MB_YESNO          ' Constant
   dim MB_NO             ' Constant

   MB_YESNO = 4          ' Type of MessageBox
   MB_NO = 7             ' Return Value of MessageBox
      
   if CheckBox.checked then
      installed = frTop.InstallEngine1.IsComponentInstalled( CheckBoxName )
      if installed = 1 then
         answer = MsgBox( LongName & " is already installed.  Do you want to reinstall this component ?", MB_YESNO, "Internet Client SDK")       
         if answer = MB_NO then
            CheckBox.checked = FALSE
         end if
      end if
   end if   

   if CheckBox.checked then
      Call frTop.InstallEngine1.SetAction( CheckBoxName, 1 )
   else
      Call frTop.InstallEngine1.SetAction( CheckBoxName, 0 )
   end if

call UpdateTimeTotals(0)
End Sub

Choosing a directory

As I mentioned earlier, a limitation of Active Setup 1.0 is that you cannot choose multiple directories for installation. The SDK team’s control prompts the user for the desired installation directory, stores the directory information in the Registry, and calls into the ADPACK.DLL utility to run the SDK .INF file. When the .INF file runs, it reads the Registry information and substitutes the user-desired directory with a default directory.

Calculating download time

Another interesting piece of scripting in the source is the code that calculates the estimated download time for the chosen components. As you can see from the code below, this calculation is based on the assumption that the client is running at 28.8 bps. This is a pretty standard modem connection, and you could alter this code to provide estimated times based on other connection speeds:

Sub UpdateTimeTotals(bTestCondition)

   ' This routine is able to compute an estimated time to download applications.

   dim downloadsize      ' The size of the files to be downloaded.
   dim downloadtime      ' The total time required to download all applications.
   dim downloadmin       ' The minutes section of the time required.
   dim downloadhr        ' The hour section of the time required.

   ' Request total downloadsize from install engine
   downloadsize = frTop.InstallEngine1.TotalDownloadSize
   'if ( bTestCondition = TRUE AND downloadsize > 0 ) then
   '     if frTop.InstallEngine1.IsComponentInstalled("CommonTech") <> 1 then
   '        downloadsize = downloadsize + frTop.InstallEngine1.Size("CommonTech")
   '      end if
   '     if frTop.InstallEngine1.IsComponentInstalled("CommonDoc") <> 1 then
   '         downloadsize = downloadsize + frTop.InstallEngine1.Size("CommonDoc")
   '   end if
   'end if
   downloadtime = CLng(((downloadsize*1024) / 28800) * 8 )
   downloadhr = frTop.Main1.CorrectHour(downloadtime)
   downloadmin = CInt((( downloadtime - CLng( downloadhr * 3600) ) / 60 ))
   'MsgBox CSTR(downloadtime) + " " + CSTR(downloadhr) + " " + CSTR(downloadmin)

   ' Get ready to formulate the string to display time to user.
   if ( downloadtime < 3600 ) then
        frControl.Totals.Caption = CSTR(downloadsize) + " KB" + "/ " + CSTR(downloadmin) + " min"
   else
        if ( downloadtime = 3600 ) then
             frControl.Totals.Caption = CSTR(downloadsize) + " KB" + " / " + " 1 hr"
        else
             frControl.Totals.Caption = CSTR(downloadsize)+" KB" +" / " + CSTR(downloadhr) + " hr" + " " + CSTR(downloadmin) + " min"
        end if
   end if
End Sub 

Function GetCompTimeStringFromSize( CompSize )
   GetCompTimeStringFromSize = CSTR(CLNG( CompSize / downloadspeed ))
End Function

Handling licensing agreements

The final area to show you is how the SDK team dealt with popping up appropriate licensing agreements. Depending on what the user checks off, various combinations of licensing agreements should be shown to the user. The user must accept the license agreement terms before the bits can be downloaded. The team used VBScript to check which items were chosen for download and show the appropriate licensing agreements (saved in text files). You can see this code if you view the source from your browser. 

But what about that nifty next button?

Okay, there’s one more little item that you might be interested in. At the bottom of the Web page, there’s a nifty bit of text that says “Next” with 4 colored arrows to the right of it. You click that button to continue (okay, so you figured that out already). The SDK team created the .GIF and used JavaScript to handle the click event on it:

<A HREF=”JavaScript::NextPage()”>

Summary

This article should give you some idea of what Active Setup is and how it can be used in real-world situations (like downloading an SDK!). This article is meant to be used as a simple overview and general guide. It is always best to check the documentation in the Internet Explorer Administration Kit for complete details about this and other Internet Explorer 4.0 technologies.

Did you find this article useful? Gripes? Compliments? Suggestions for other articles? Drop me a line at nancycl@microsoft.com and let me know.