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:
- 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.
- 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.
- Your application can then read the XML file, post its own user interface and allow the user to select the updates they require.
- 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.
- 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:
- The script
- Calling the Software Update Wizard for the first pass (to parse the script/generate
the XML file)
- The XML file
- Calling the Software Update Wizard for the second pass (to action the required updates)
- Other considerations
- Script keywords specific to 2-pass updates
More..
This is the update script on the server. (The keywords which are unique to
2-pass updates have links to the keyword detail page,
and are also detailed separately below.)
[1]¶
RunAlways¶
Group=OfficeUpdates¶
Priority=1¶
PlatformMin=1,4,90¶
PlatformMax=2,6,0¶
TargetFolder=<PROGRAMFILES>\PCWriter¶
CheckFile=<SYSDIR>\PCWriter.exe<Version=7.0.6000.16386>¶
Zipfile=http://www.myserver.com/updates1.zip¶
ShortMessage=<*040c*>Evoquant
mise à jour pour PCwriter utilitaire¶
ShortMessage=Outlining update for PCwriter utility¶
LongMessage=<*040c*>Cette
mise à jour ajoute de nouvelles et très fonctionnels
décrivant les capacités de votre PCwriter logiciel. Les mises à jour sont entièrement
compatibles avec Open Office Writer, ainsi que Microsoft Word¶
LongMessage= This update adds new and highly functional outlining capabilities
to your PCwriter software. The updates are fully compatible with Open Office
Writer as well as Microsoft Word¶
KillProcess=Notepad.exe¶
XML_FileVersion=<SYSDIR>\PCWriter.exe
XML_Spare=<Dependency>PowerManagement</Dependency>
¶
[2]¶
RunAlways¶
Group=OfficeUpdates¶
Priority=5¶
PlatformMin=2,6,0¶
PlatformMax=2,6,0¶
Filename=http://www.myserver.com/dictionary.dat¶
TargetFolder=<CLIENTFOLDER>\dictionary¶
ShortMessage=<*040c*>Spelling
corrections pour PCwriter utilitaire¶
ShortMessage=Spelling fixes for PCwriter utility¶
LongMessage=<*040c*>Fonctionnalités
améliorées pour les orthographes anglais
ordinateurs! Aussi grammatical!¶
LongMessage=Feetures improvd spelings for Inglish computers! Aslo gramer chekers!¶
¶
[3]¶
RunAlways¶
Group=PowerManagement¶
Priority=3¶
PlatformMin=1,6,0¶
PlatformMax=2,6,0¶
SubmitVariable <WUWUIFOLDER>=HKEY_LOCAL_MACHINE\SOFTWARE\Web Update Wizard\WuWUIFolder¶
TargetFolder=<WUWUIFOLDER>¶
Zipfile=http://www.myserver.com/WuWIupdate.zip¶
ShortMessage=<*040c*>Spelling
corrections pour PCwriter utilitaire¶
ShortMessage= Additional power management capabilities for your PC¶
LongMessage=<*040c*> Cette mise à jour ajoute corps à détection automatique
sommeil capacités à votre PC. Il enverra votre PC dormir lorsqu'il détecte votre
chaleur corporelle s'éloigner de l'appareil. Lorsque vous approchez de l'appareil,
il sens votre chaleur corporelle et de commuter automatiquement sur.¶
LongMessage=This update adds body-sensing auto-sleep capabilities to your PC.
It will send your PC to sleep when it senses your body heat move away from the
device. As you approach the device it will sense your body heat and automatically
switch on.¶
¶
[4]¶
RunAlways¶
Group=OfficeUpdates¶
Priority=2¶
PlatformMin=1,4,0¶
PlatformMax=2,6,0¶
Zipfile=http://www.myserver.com/misc.zip¶
ExecAfter=<CLIENTFOLDER>\SetupNewtuff.exe<AsUser><Wait=Yes>¶
ShortMessage=<*040c*>Diverses
petites améliorations.¶
ShortMessage=Various small enhancements¶
LongMessage=<*040c*>Un <i>grand nombre</i> de nouvelles fonctionnalités
pour votre PC! <a href="http://www.PC.com/newinfo.html">Cliquez
sur ce lien</a> pour plus d'informations.¶
LongMessage=Lots of <i>great new features</i> for your PC! <a
href="http://www.myserver.com/newinfo.html">Click this link</a>
for more information.¶
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.
top
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.
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.
<?xml version="1.0" encoding="utf-8"?>
<WebUpdateWizard Version="4.5">
<Group Name="OfficeUpdates">
<Update>
<Id>1</Id>
<Priority>1</Priority>
<ShortMessage>Outlining update for PCwriter utility</ShortMessage>
<LongMessage>This update adds new and highly functional outlining capabilities to your PCwriter software. The updates are fully compatible with Open Office Writer as well as Microsoft Word</LongMessage>
<XML_FileVersion Name="C:\Windows\System32\PCWriter.exe">6.0.0.0</XML_FileVersion>
<Dependency>PowerManagement</Dependency>
</Update>
<Update>
<Id>2</Id>
<Priority>5</Priority>
<ShortMessage>Spelling fixes for PCwriter utility</ShortMessage>
<LongMessage>Feetures improvd spelings for Inglish computers! Aslo gramer chekers!</LongMessage>
</Update>
<Update>
<Id>4</Id>
<Priority>2</Priority>
<ShortMessage>Various small enhancements</ShortMessage>
<LongMessage>Lots of
<i>great new features</i>for your PC!
<a href="http://www.PC.com/newinfo.html">Click this link</a>for more information.</LongMessage>
</Update>
</Group>
<Group Name="PowerManagement">
<Update>
<Id>3</Id>
<Priority>3</Priority>
<ShortMessage>Additional power management capabilities for your PC</ShortMessage>
<LongMessage>This update adds body-sensing auto-sleep capabilities to your PC. It will send your PC to sleep when it senses your body heat move away from the device. As you approach the device it will sense your body heat and automatically switch on.</LongMessage>
</Update>
</Group>
</WebUpdateWizard>
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.
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
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:
- the Software Update Wizard download dialog box, which will be displayed unless you
use the <noui> option in your
Filename, Zipfile or
AdditionalFile keyword lines.
- the unzipping progress box for Zipfile
will be displayed unless you use the <noprogress> option.
top
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