Here is an example of the Web Update Wizard in action, from adding it to your software application through to delivering an updated version to your customers.
There are 2 ways of initiating a Web Update Wizard session.
If you are using the wuw4.dll Windows Dynamic Link Library to launch updates, your need to reference the wuw4.dll file in your project or dynamically load it at run time.
The wuwinstaller.exe package provided with the Web Update Wizard contains the files you need to redistribute to your users - see Deployment.
In VB, declare a function prototype:
Private Declare Function WebUpdate Lib "wuw4.dll" (ByVal URL As String) As Long
Note that the "ByVal" switch is required.
In C/C++, you should include the supplied wuw4.lib library file in the Link / Object /library modules section of your project's build settings.
Also, include the WebUpdate.h file in the source file which uses the dll's WebUpdate() function.
Alternatively, you can use LoadLibrary() API at runtime to use the wuw4.dll module.
In C#, you should include the following 'Using..' line:
using System.Runtime.InteropServices;
Then declare an instance of class wuw within your class declaration:
public class
{
[DllImport("wuw4.dll")]
public static extern bool WebUpdate(string URL); // Asynchronously
// or...
[DllImport("wuw4.dll")]
public static extern int WebUpdateWait(string URL, UInt32 nTimeOut); // Synchronously
}
If you are using the wuwstub.exe application to launch updates you should install it in the same folder as your application's exe.
At the time you want the client user to be able to check for updates, make a call to the WebUpdate(URL) or WebUpdateWait(URL, TimeOut) function from the wuw4.dll DLL. You can either do this as part of the opening process of your application (so that the update check happens without any user intervention) or in response to a button click / menu selection by the user.
The difference between WebUpdate() and WebUpdateWait() is that WebUpdate() operates asynchronously with your application whereas WebUpdateWait() operates synchronously. In other words, WebUpdate() calls the Web Update Wizard and returns control to your application immediately, whereas WebUpdateWait() launches the Web Update Wizard and only returns control to your application once the Web Update Wizard has finished, or when the specified number of milliseconds from launch has finished, whichever occurs earlier.
Please note that the Web Update Wizard uses a MBCS (Multi-Byte Character Set) build throughout. If your application uses Unicode you must ensure that URLs passed to the Web Update Wizard are converted from Unicode to MBCS using, for example, the WideCharToMultiByte() Windows API function.
In VB, you would issue a call with the following code:
Private Sub CommandButton1_Click()
Dim myURL As String
myURL="http://localhost/prophecy/prophecyupdate.txt"
WebUpdate(myURL)
End Sub
In C/C+, you would issue a call with the following code:
WebUpdate(_T("http://localhost/prophecy/prophecyupdate.txt"));
orWebUpdateWait(_T("http://localhost/prophecy/prophecyupdate.txt"), 60000);
Note that if your application is built using Unicode then you will need to convert the URL to a MBCS string using the WideCharToMultiByte() Windows API function.In C#, you would issue the call with the following code:
wuw.WebUpdate( "http://localhost/prophecy/prophecyupdate.txt" );
.. or ..
wuw.WebUpdateWait( "http://localhost/prophecy/prophecyupdate.txt", 6000 );
Your application will carry on processing upon return from WebUpdate(). Note that the WebUpdate() function will complete execution almost instantly - it simply passes the URL though the named pipe to the Web Update Wizard Service and then returns.
If you are using the wuwstub.exe application instead of the dll, simply launch it with the URL of the server script file passed as an argument, as shown in the following code snippet:
ShellExecute(NULL, "open", "wuwstub.exe", "http://www.myserver.com/updatescript.txt", NULL, SW_HIDE);
Note that it is only possible to interoperate synchronously with the Web Update Wizard using the wuw4.dll dynamic link library. However, if you wish to interoperate synchronously and use wuwstub.exe, there is a workaround. The Web Update Wizard maintains the following REG_DWORD registry key:HKEY_LOCAL_MACHINE\SOFTWARE\WUW\UsageCounter
The value of this counter is incremented every time the Web Update Wizard finishes a call, irrespective of whether it processes any updates and irrespective of whether it was actually able to access the internet. It's purpose is simply to count the number of times your application has called the Web Update Wizard. Therefore, you can capture its current value before launching the Web Update Wizard, and then continue looping and rechecking its value until its value is incremented. As soon as its value is incremented your application can exit the loop and continue as normal.Please refer to the Deployment help topic for advice and information on installation options for the Web Update Wizard.
Suppose you now want to deploy a new version of your application or one of its components to all your customers. First, you upload the new version to your web server. In this example, we will upload it to the <wwwroot>/webupdate folder on the server (i.e. a subfolder named 'webupdate' off the root of your web site). The Web Update Wizard can also download and unzip ZIP files, but in this basic example we will just upload an uncompressed version of the update file.
Next, we need to upload an update script file to <wwwroot>/webupdate (i.e. to the URL referred to in our WebUpdate() call from steps 1 and 2 - http://www.dp.co.uk/webupdate/webupdate.txt ).
An update script is a simple ANSI formatted text file.
The update can be made optional (i.e. the user can choose whether to accept
or reject it at this time) or compulsory (i.e. the update happens automatically).
In this example, we will make it optional.
You may find the supplied Web Update Wizard Project Manager utility useful for managing your script authoring, testing and uploading. There are also syntax definition files for a couple of popular shareware/freeware text editors, TextPad and PSPad, included in this package - click here for more information.
The following script file section will do the business:
[1]
Filename=/webupdate/myapplication.exe
KillProcess=myapplication.exe
Message=There is an updated version of MyApplication.exe available. Would you like to install it now?
Importance=Optional
Backup=Yes
Each keyword is documented in the keywords reference page. You can also quickly jump to a keywords list sorted alphabetically or by category by clicking the 'Keywords' button at the top of this help file:
The ' Filename= ' keyword is the relative location of the update file on the web server.
' KillProcess= ' closes all running instances of myapplication.exe (in order that they may be updated and then restarted after the update without causing a file sharing violation). There are other options for replacing in-use files - see WindowTitle=, MoveFileEx= and Reboot in the keyword help sections.
The ' Message= ' posts a message to the user prior to downloading the update, which, in conjunction with the ' Importance= ' keyword provides the user with 'Yes' and 'No' buttons in order to choose whether to accept the update at that time.
Finally, the ' Backup=Yes ' keyword backs up the previous version of the file as 'myapplication.bak'.
The ' [1] ' at the top of the quoted section is a counter which the Web Update Wizard uses to deduce whether it has already downloaded the update.
There are further keywords which give you greater control over whether updates are needed - see CheckFile, CheckFileExists, FileDate and FileVersion.
Note that update scripts also support the automatic unzipping of zip format files, and that you can launch one or more programs either before or after your software file is downloaded from the server.
There are additional examples of Web Update Wizard scripts here.
The user launches myapplication.exe and it initiates an update calling the WebUpdate() function of wuw4.dll or by passing the script URL as an argument to wuwstub.exe. Wuwstub.exe must be located in the same folder as your running application. Wuw4.dll is installed by our wuwinstaller.exe redistributable installer (see Deployment) and is normally in the 'Windows\System32' folder.
(Wuwstub.exe is actually linked to wuw4.dll and it calls the exported WebUpdate() function. The process from wuwstub.exe on is therefore the same as if your application has called wuw4.dll's exported function.)
The wuw4.dll component communicates the file path of the update script on the server ( http://www.dp.co.uk/webupdate/webupdate.txt ) to the Web Update Wizard service and also launches the Web Update Wizard User Interface component (WuWUI.exe) which provides all interaction with the user.
WebUpdateSvc4.exe then downloads the update script file and processes it. It sends messages to WuWUI.exe whenever it needs to interact with the user, and receives messages back from WuWUI.exe whenever appropriate to the context it is pricessing.
If the update counter on the target PC is less than the counter in the update script section (see above) it processes that section of the update script. Otherwise, no user interaction occurs. The Web Update Wizard running as a service instructs WuWUI.exe to close and then goes back to sleep, awaiting another communication through the named pipe.
This is the sequence the user sees:
(a) Your application starts up as normal and calls the Web Update Wizard dll / wuwstub.exe application within its start-up code:
(b) The Web Update Wizard DLL / wuwstub.exe application communicates the server update script URL to the Web Update Wizard service through a named pipe. Your application continues as normal.
(c) The Web Update Wizard service downloads the script file from the server if the user is on line. Otherwise it simply returns without any further action.
(d) If the user is on line and the script file contains a relevant update the Web Update Wizard will process the script. The user will then see the following dialog message:
(e) If the user decides to install the update (by clicking 'Yes') then the Web Update Wizard will attempt to close all running instances of "Your Application" and post an (optional) warning before it closes them. Note that Windows will not allow an open file to be overwritten - therefore the Web Update Wizard has to close any instances of the application that are running on the client PC.
(f) The Web Update Wizard will close the nominated windows (applications) and download and install the update file, backing up the previous version to myapplication.bak. The user will see the following (optional) success message (or your own custom message):
(g) The Web Update Wizard will then restart myapplication.exe (i.e. the newly updated version) and the user's session will continue as normal.
Note that the Web Update Wizard maintains a log file in the same folder as WebUpdateSvc4.exe. The purpose of the log file is to maintain a cumulative record of updates processed and to assist in problem-solving, should your script fail for any reason. You may turn logging off in your update script using the keyword "LoggingOff", and back on with "LoggingOn".
In addition to standard logging, you can switch on verbose logging on a PC by PC basis by editing the WebUpdateSvc4.ini file. If you change the 'SuperLogging' entry to 'Y' then the WebUpdateSvc4.log' file will comprehensively track the progress of the update script. The default for this setting is 'N' as otherwise the log file will grow rapidly.
In addition, the Web Update Wizard can create an XML status file called 'LastUpdate.xml' in your application's folder which contains status information relating to the last URL processed by the Web Update Wizard. Your application can read it after the update in order to understand the result of the update. Here is an example from a failed call, with all the available tags included:
<WuW>
<InternetConnectedState>1</InternetConnectedState>
<WuWVersion>4.0.0.6</WuWVersion>
<LastRun>06/06/2005 - 20:29:37</LastRun>
<LastURL>http://www.mycompany.com/scripy.txt</LastURL>
<LastHttpCode>404</LastHttpCode>
<ErrorText>Failed to receive a valid HTTP response from the server.
«
(Check download URL in script!)</ErrorText>
<RunCounter>11</RunCounter>
</WuW>
The LastUpdate.xml file contains one or more of the following tags:
| InternetConnectedState | This key will be '1' if there was an active internet connection available, otherwise it will be '0'. (This is the BOOL value returned from an InternetGetConnectedState() Wininet call.) |
| WuWVersion | The version number of the Web Update Wizard that processed the last URL. |
| LastRun | The date and time of the last run of the Web Update Wizard, in dd/mm/yyyy - hh:mm:ss |
| LastURL | The last URL which the Web Update Wizard processed. Typically this will be either your update script (if no update was required) or the update file (if an update was required). |
| LastHttpCode | The last http: status code. 200 means it worked! |
| ErrorText | A formatted error message, including the http status code. |
| RunCounter | The value of the 'HKEY_LOCAL_MACHINE\SOFTWARE\WUW\UsageCounter' registry counter, which the Web Update Wizard increments at the end of every update process, irrespective of whether an update was actually made. (See WebUpdateWait() ). |
The Web Update Wizard decides which of the tags to write by reading the previous file and just populating the tags it finds. If you want to use the LastUpdate.xml file in your application to provide additional feedback to the user about the last update then you simply need to install / write a starter LastUpdate.xml file into your application's folder. The starter file should simply contain the tags you want recorded. For example, if all you want to know is whether the user was connected to the internet or not at the time of the last WebUpdate() call, your starter LastUpdate.xml would look like this:
<WuW>
<InternetConnectedState></InternetConnectedState>
</WuW>
The Web Update Wizard thens populate the tag with the connected state each time it runs but omits all the other tags listed in the table above.
Be careful when your application loads this file. You may need to wait until the Web Update Wizard has written it by checking its Last Modified date.
That's it! Easy to deploy, easy to use, and minimising interruption / workload for your customers! The Web Update Wizard can also do things like replacing in-use files, initiating a reboot etc.. Please see the Keywords Reference page for more information on all the available options and the Additional Example Script page for more sample scripts.