TWebUpdate documentation (v1.0) © by TMS software

Info - Installation - General info & Control files - Procedures - Properties - Events - Main page

Info

With TWebUpdate, you and your clients never have to worry again about having difficulties with updates. What can TWebUpdate do for you ? Automatically check for updated files on the Internet or Intranet Can check for updated files over http and ftp protocols or simply file based for Intranet applications Can replace running executables itself or DLLs used by the application with the updates Allows to update any other application component or data file Can just show new documentation, tips, announcements etc.. when available Allows updates based on dates or on file versions Simple VCL based component to transfer files over http or ftp and to handle and check LAN or dialup based Internet connections, so no extra DLL's or OCX's required to include. Very compact size and simple interface Can automatically download & extract multilevel directory CAB files Download TWebUpdate component & documentation for Delphi 3, 4, 5 and C++Builder 3, 4, 5 here : wupdate.zip Sample application that can be automatically updated (test .EXE included) : sampapp.zip

Installation

Delphi 3, 4, 5 : In the Component menu, select Install component, Into new package, browse for wupdreg.pas and choose package name.

C++Builder 3.0, 4.0, 5.0 : In the Component menu, select Install component, Into new package, browse for wupdreg.pas and choose package name.


General info & Control files

1) Choosing the update distribution method, ie over http, ftp or file-based.
This is set in the property : UpdateType : httpUpdate, ftpUpdate, fileUpdate

2) Set additional parameters dependent of distribution type set :

For FTP based distribution
- HOST : ftp server name
- FTPDirectory : directory where update files are
- PORT : ftp port to use (default 21)
- UserID, Password : FTP server username & password (leave blank for anonymous FTP)
- Proxy, ProxyUserID, ProxyPassword : proxy server name, username & password (leave blank when no proxy is used)
- URL : location of the update control file (ie. update.inf)
- FTPPassive : set true for passive FTP mode

For HTTP based distribution
- Proxy, ProxyUserID, ProxyPassword : proxy server name, username & password (leave blank when no proxy is used)
- URL : full location of the update control file (ie. http://www.yourserver.com/updates/update.inf)

For file based distribution
- URL : UNC of the update control file

3) Build the update control file

The update control file is a .INI organized file to control the
update. Following sections and keywords can be used :

The general update section

1) date based updates :

[update]
date=16/2/2000

This date is compared with the date of the last update (stored in the registry at a location as specified in the LastURLentry property) If the date is later than the date found in the registry, the update continues.
Notice : the data format can be specified in the dateformat property of TWebUpdate to allow both US and Euro dates.

2) version based updates :
[update]
newversion=1,1,0,0
localversion=application.exe

The new version (major,minor,release,build) is compared with the version info available in the application as specified at the localversion keyword. If the newversion is newer than the version found in the .EXE (or .DLL) file, the update continues.


Actions to do for the update

These actions are specified in the [action] section

[action]
updateURL=http://yourserver/update.inf
msg=Automatic web update
query=This is the update version 1.5.0.0 Continue ?
showURL=http://www.yourserver.com/updates/doc.htm
htmldlg=http://www.yourserver.com/updates/dialog.htm
runbefore=
runafter=

In the action section following keywords are supported :
- updateURL : will update the URL of the update control file
- msg : simple message displayed during the update
- query : query string allowing the user to cancel the update
- showURL : shows the URL in the default browser
- htmldlg : shows the specified html file at the URL as dialog
- runbefore : run any app. before the update starts
- runafter : run any app. after the updated files are transferred

Number of files to update

The number of new files are defined in the sections [files] with the count keyword

[files]
count=2

Details of files to update

[file%] (where % is number of the file starting at 1)
url=URL (HTTP), filename (FTP) or UNC (file based)
newversion=1,0,0,0
localversion=application.exe
targetdir=path
descr=your description of the file
compressed=1

If no newversion keyword is present, the file is downloaded anyway, otherwise this new version is compared with the version info available in the local file defined after the localversion keyword
The path can be any path and can also contain prefixes : {APP}, {WIN} or {TMP}. If a file must be installed into a subdirectory of the current application running the update, specify {APP}\SUBDIR. If I file must be installed in a subdirectory of the Windows directory use {WIN}\SUBDIR or in the temporary directory with {TMP}\SUBDIR.
Custom prefixes can also be used and these need to be translated to real directories on the system using the OnConvertPrefix event. The descr details are only used when the OnGetFileList event is used. The OnGetFileList event can be used to query the user for all available updates based on a description rather than the file name. If compress is 1, this means that the file should be decompressed using the lzexpand algorithm, otherwise it is copied.
As an alternative, TWebUpdate also automatically recognizes the .CAB extension and if the property CABExtract is true, these CAB files are extracted as well during the update process. Make sure though that no application components (ie .EXE and .DLL files) are decompressed in this step. These need to be decompressed in the section [Application] which is discussed further.

Updating application components
To overwrite used .EXE and .DLL files of the running application with the updated files, other file with different names than the ones in use must be used. For the files in use, these can be compressed with the standard Microsoft LZ compression program (COMPRESS -r <file>) When updating, the running application is closed, the files are expanded and the running application (update version) is restarted. The appupdate=1 keyword indicates if application used components need to be updated. The application that must be restarted after the update
is indicated with the appname keyword. Finally, the appcomps keyword indicates a series of LZ compressed files that will be expanded during the update process :

[application]
appupdate=1
appname=inet.exe
appcomps=inet.ex_ other.dl_ onemore.dl_

As an alternative CAB files are now also supported giving the extra flexibility to have long filesnames for application EXE and DLLs files. Instead of specifying the LZ compressed filenames, just add the CAB file names in the appcomps keyword, ie.

[application]
appupdate=1
appname=CABFileUpdateApp.exe
appcomps=newversion.cab

Additional custom validation options

Custom validation can be done based on entries in the control file as well. This is done through the OnCustomValidate event which passes the values found in the following section of the control file :

[custom]
validatemsg=
validateparam=

This could for example be used to query for a valid password or license to obtain the update. The update will continue if the customvalidate parameter is true upon return.

Other than validation, custom processing of parameters can be done as well through the OnCustomProcess event in which following info from the control file is passed :

[custom]
processmsg=
processparam=


4) Doing updates in the application

The method to start the update is TWebUpdate.DoUpdate.

Two properties control the process :

UpdateConnect can be:

wucNoConnect : check to see if connected to the Internet but do not try to establish a connection
wucConnectPrompt : try to establish a connection if none is available with the standard dialup prompt
wucConnectSilent : try to establish a connection if none is available in silent mode
wucConnectPromptHangup : hangup if connection was required after update
wucConnectSilentHangup : hangup if connection was required after update

UpdateUpdate can be:

wuuSilent : no prompts for all files that will be downloaded
wuuPromptAll : prompt for every file to be downloaded
wuuPromptOnce : prompt just once for downloading updated files

The DoUpdate method can be called from a menu in the application or called
from a timer component to handle this automatically.

Example update control file :

[update]
date=16/2/2000

[action]
msg=Automatic web update
query=This is the update of 16/2/2000. Continue ?
showURL=http://www.tmssoftware.com/wupdate.htm

[files]
count=1

[file1]
url=http://www.tmssoftware.com/wupddoc.htm


5) Language customization

The messages that appear in popup dialogs are now in the resource file WUPDENG.RES and in english. Language customization can be done by replacing the strings in this RES file. All other messages can be changed through events and decided upon which have to appear in the user interface.

Procedures

procedure DoUpdate; start the normal update process
procedure DoThreadUpdate; start the threaded update process

Properties

property DateFormat:string; format of the date in the .INF file
property DateSeparator:char; date separator used in the date in the .INF file
property FTPDirectory:string; default login FTP directory
property FTPPassive:boolean; when true, uses passive FTP mode
property Host:string; FTP host name
property CABExtract:boolean; extract CAB files during download process
property Password:string; FTP user password
property Port:integer; FTP port to use (default 21)
property Proxy:string; name of proxy server (if used, otherwise leave blank)
property ProxyUserID:string; username for proxy server (if used, otherwise leave blank)
property ProxyPassword:string; password for proxy server (if used, otherwise leave blank)
property UpdateType:TWebUpdateType; set type to http, ftp or file based updates
property UpdateConnect:TWebUpdateConnect; actions to take to connect to the internet (if required)
property UpdateUpdate:TWebUpdateUpdate; updatemethod
property URL:string; location of update control file for http or file based updates
property DateFormat:string; date format used for date based version checks
property UserID:string; FTP user name
property LastURLEntry:TLastURLEntry; registry location for updated locations for web updates
property PostUpdateInfo:TPostUpdateInfo: property holding settings for posting custom data to the server during the update.

Events

property OnFileProgress:TWebUpdateFileProgress; event called for file download progress
property OnFileVersionCheck:TWebUpdateFileVersionCheck; event called for custom version checking for each available file in the update.
property OnProgress:TWebUpdateProgress; event called for each step during the web update
property OnProgressCancel:TWebUpdateProgress; event called during update to allow cancelling updates while busy
property OnStatus:TWebUpdateStatus; event for status messages during web update
property OnThreadUpdateDone; event called when
property OnAppRestart:TWebUpdateRestart; event called before restarting downloaded new version
property OnAppDoClose:TWebUpdateDoClose; event called to allow the application to execute its own close method
property OnCustomValidate:TWebUpdateCustomValidate; event called when custom validation info is present in the control file.
property OnCustomProcess:TWebUpdateCustomProcess; event called when custom update processing info is present in the control file.
property OnGetFileList:TWebUpdateFileList; event called to allow user to select from multiple updated files
property OnConvertPrefix; TWebUpdateConvertPrefix; event called to allow user to convert directory prefixes into directory on the system.