2-Pass Mode - Handle the User Interface in Your Own Application

Overview

In standard, '1-pass' mode, you pass the Software Update Wizard the URL of your update script and it handles the entire update process from then on, including any UI (user interface) interaction with the user.

In the majority of cases this provides a simple, rapidly implemented plug-in solution for automatic updates with the minimum of coding on your part.

However, if you would like your application to handle all or the majority of the UI then the Software Update Wizard can also operate in '2-pass' mode.  In this mode, the Software Update Wizard works like this:

  1. Your software calls the update script (which includes additional special syntax options unique to 2-pass updates and which are described below).  When you pass the update script URL to WuW4.dll or wuwstub.exe in your WebUpdate() or WebUpdateWait() call you append the tag "<MODE=1>" to the URL to indicate that you wish to work in 2-pass mode.
  2. The Software Update Wizard downloads the update script from your web server and parses it for updates as usual.  However, instead of processing the updates that apply it instead creates an XML file containing the details of the updates that apply for this user and then returns control to your application without further processing.
  3. Your application can then read the XML file, post its own user interface and allow the user to select the updates they require.
  4. When your application knows which updates it would like the Software Update Wizard to action it calls the Software Update Wizard a second time.  This time it appends the tag "<MODE=2>" to the script URL, together with a list of the update section IDs or groups that need to be actioned by the Software Update Wizard.
  5. The Software Update Wizard receives this call and processes the required script section IDs and groups, updating the user's software.

In other words, the Software Update Wizard parses the update script twice - the first time to generate the XML file and the second time, in response to your application's call, to execute the required updates.

A Worked Example

Contents:

  1. The script
  2. Calling the Software Update Wizard for the first pass (to parse the script/generate the XML file)
  3. The XML file
  4. Calling the Software Update Wizard for the second pass (to action the required updates)
  5. Other considerations
  6. Script keywords specific to 2-pass updates

The script

More..

Each script section ID (the '[1]', '[2]', etc in the script) is assigned to a named Group and is given a numeric Priority value.

The Group name allows updates from several sections to be handled by the Software Update Wizard as a single group, so that the second pass call can refer to the Group name in order to action all the updates within that group.

The Priority value has no meaning to the Software Update Wizard but is written to the XML file and can allow your application to filter updates based on their priority.

The ShortMessage and LongMessage lines allow you to provide two strings of variable length which are also written to the XML file.  You can use these strings in your UI to advise the user of the updates that are available.

Note that ShortMessage and LongMessage support multiple language entries, as described here.  Only the entries that correspond to the user's Windows Regional Settings will be written to the XML file.  If there is no matching language ShortMessage and LongMessage then the default language message will be written..

The XML_FileVersion= line gets the Software Update Wizard to include a <FileVersion Name> tag in the generated XML file, which the controlling application can use in deciding whether an update is applicable.  You can use as many of these lines within a single update script section as you require.

The XML_Spare= line allows you add a custom tag to the generated XML file, which can help the controlling application with additional information to present the user or to help the application determine which updates it would like the Software Update Wizard to process in its second pass.


Note: Only the script sections which pass the update tests will be written to the XML file.  The update tests are the PlatformMin, PlatformMax, CheckFile and FileVersion keywords.

top

Calling the Software Update Wizard for the first pass

In the calling application you signify that a 2-pass process is required by appending the (case-sensitive) tag "<MODE=1>" to the URL in the WebUpdateWait() or WebUpdate() call:

WebUpdateWait("http://www.myserver.com/updatescript.txt<MODE=1>", 10000);

 

You can use either WebUpdate() or WebUpdateWait() for the first pass.  However, you will probably find WebUpdateWait() more suitable because it waits until the Software Update Wizard has finished parsing the update script and created / updated the target XML file before returning control to the calling application.  If you use WebUpdate() instead then your application will need to detect the existence / timestamp change of the XML file itself.

XML File

The XML file, WuWUpdates.xml, which is generate by the first pass of the Software Update Wizard is created in the standard Windows folder relating to the CSIDL corresponding to CSIDL_COMMON_APPDATA - see http://msdn2.microsoft.com/en-us/library/bb762494.aspx for more information.

(Note: Your application should use a Windows API function to discover the folder which equates to CSIDL_COMMON_APPDATA on the user's computer - e.g. SHGetSpecialFolderPath() or SHGetFolderPath() rather than assuming it will be created in the same folder as it is created on your test/development machine.)

Click here to see an example of the XML file which is generated by pass-1 of the Software Update Wizard.

As you can see from the expanded XML only the update sections which are relevant to the client computer are written to the XML file.

If you use the Predownload option in a <MODE=1> 2-pass update script then an additional <Download> element will be included in each Update section of the XML file.  If the predownload succeeded the <Download> element will contain the text "OK".  If it failed then the reason for the failure will be written to the <Download> tag, staring with the text "Failed:", followed by the error text as returned from the WinInet download api calls.

If the Software Update Wizard is unable to download the update script because your web server is down or the user is disconnected from the internet, a WuWUpdates.xml file will still be generated. However, it will just contain a single element, "<Error>", indicating network failure. 

Calling the Software Update the second time to action the required updates

Once the Software Update Wizard has parsed the update script during its first pass your application must decide which update sections or Groups it would like the Software Update Wizard to action in its second pass.

Your application tells the Software Update Wizard which items should be actioned by a second WebUpdate() or WebUpdateWait() call:

WebUpdate("http://www.myserver.com/updatescript.txt<MODE=2>PowerManagement,OfficeUpdates,[8]");

The WebUpdate call shown above causes the Software Update Wizard to action the update groups 'PowerManagement', 'OfficeUpdates' and also section '[8]' of the update script.

The required items can be listed in any order, separated by commas (with no spaces) and will be actioned in the order in which they appear in the original update script (rather than the order you supply in your WebUpdate() call).

The XML file and also the update script file which were generated from pass 1 and which are saved in the CSIDL_COMMON_APPDATA on the user's computer will NOT be deleted by default.  However, they will be replaced by the next <MODE=1> call.  That means your application can make several <MODE=2> calls for one <MODE=1> call.  The benefit of this is that you can have your application process each update group or section separately and provide feedback to the user through your application's interface during the update process.

If you would like the XML file and the update script file which were generated from pass 1 to be deleted in your <MODE=2> call then simply append the text "<CLEANUP>" to your <MODE=2> url. as in:

WebUpdate("http://www.myserver.com/updatescript.txt<MODE=2>PowerManagement,OfficeUpdates,[8]<CLEANUP>");


All other elements of the update process are the same as single pass scripts.

top

Other Considerations

In 2-pass mode all Software Update Wizard message and warning boxes are suppressed.  Therefore if you use a KillProcess line, for example, the target application will be terminated without warning.

The only exceptions to the suppression of the user interface are:

top

Keywords specific to 2-pass scripts

The following keywords are specific to 2-pass scripts.

Group=
Description
This keyword is used in 2-pass update scripts and allows you to link an update section to a named group of updates.  When the controlling application for the 2-pass update parses the XML file which the first pass generates it can then specify which update groups should be processed in the second pass.

A Group name can be any alphanumeric text value.
Example
Group=dllupdates2
Default (if not used)
If you are using 2-pass updates then this keyword is required.  If you omit it the section with be ignored and will not be included in the generated XML file.

If you use this keyword in single-pass updates it will simply be ignored.
Priority=
Description
This keyword is used in 2-pass update scripts and allows you to assign a numeric priority value to the update section in which the keyword line resides.  It is not used by the Software Update Wizard, but is included in the XML file generated by the first pass scan.  Your application can then parse the XML file and decide which updates need to be processed based on their priority, if that is what you want your application to be able to do.  Otherwise, your application can ignore the priority tag.
Example
Priority=5
Default (if not used)
The Priority tag in the XML file generated by the first pass will be -1.  If you use this keyword in single-pass updates it will simply be ignored.
ShortMessage=
Description
This keyword is used in 2-pass update scripts and allows you to specify the short message which will be written to the XML file if the section in which it resides needs to be processed in the second pass.  It allows your controlling application to pick up a short description of the update to present to the user.
Example
ShortMessage=Updates for Printing Component
Default (if not used)
If you do not include a ShortMessage line in a 2-pass update script section then the ShortMessage tag in the XML file generated in the first pass by the Software Update Wizard will be blank (empty).

The line will be ignored if you include it in a single pass update script.
LongMessage=
Description
This keyword is used in 2-pass update scripts and allows you to specify the long message which will be written to the XML file if the section in which it resides needs to be processed in the second pass.  It allows your controlling application to pick up a long description of the update to present to the user.

All other properties and behaviours are as ShortMessage
XML_FileVersion=
Description
This keyword is used in 2-pass update scripts and allows you to add a file version tag for any file on the user's computer to the XML file of available updates which is generated by the first pass.

Note that the tag will only be added to the generated XML file in the first pass if an update is actually applicable.

You can include any number of XML_FileVersion lines in an update script section.

You may use any of the Software Update Wizard's folder substitution variables.  (See TargetFolder.)

If the file referred to in the XML_FileVersion keyword line exists on the target computer and it has a version string then the version string will be written to the generated XML file in a <FileVersion..> tag.  If the file exists but it does not have a version string then the text "MissingVersionData" will be written to the <FileVersion..> tag.  If the file does not exist then the text "NotFound" will be written to the <FileVersion..> tag.
Example

XML_FileVersion=<WINDIR>\NOTEPAD.EXE

This keyword line will add the following tag to the generated XML file (providing an update is required from the script section in which the keyword line resides):

<FileVersion Name="C:\Windows\NOTEPAD.EXE">6.0.6000.16386</FileVersion>

Default (if not used)

The XML file generated by pass 1 of the 2-pass process will not contain any <FileVersion> tags.
XML_Spare=
Description
This keyword is used in 2-pass update scripts and allows you to add any number of user-defined informational tags to the XML file which is generated by the first pass of the update script.

You can use this option if the Group or Priority values for each update section are insufficient for your controlling application to determine which updates it would like the Software Update Wizard to process on the second pass or to help your controlling application with its interaction with the user.

Note that the tag(s) resulting from using this keyword will only be added to the generated XML file in the first pass if an update is actually applicable.

You can include any number of XML_Spare lines in an update script section.
Example
XML_Spare=<Dependency>OfficeUpdates</Dependency>

This keyword line will add the following tag to the generated XML file (providing an update is required from the script section in which the keyword line resides):

<Dependency>OfficeUpdates</Dependency>

The text to the right of the '=' sign in the keyword line is simply added as a tag to the generated XML file.

Default (if not used)

The XML file generated by pass 1 of the 2-pass process will not contain any additional tags.

top