Version Beta www.capesoft.com Updated Friday 31 August 2007

Jump Start	Examples	FAQs	Templates	Parameters	Version History

Please Note
	Products required for Safe Update NetTalk

Contents
		JumpStart for Downloading (do this first)
		JumpStart for Uploading (do this next)
		Introduction
		Programmer's Guide
		The Global Extension
		Downloading
		Certificate Information
		Examples
		Local Extensions
		The Safe Update Template Utility
		Control Templates The SafeDownload Control Template The SafeAutoUpdate Control Template
		Code Embeds
		Uploading
		Certificate Information
		An Uploader Example (SAFEUP)
		The Safe Update Template Utility
		Control Templates The SafeUpload Control Template The SendFTP Control Template
		Code Embeds
		FAQ
		Installation
		Support
		Purchasing Safe Update
		Distribution
		Technical Details Safe Update Class Method Reference Safe Update-Defined Events and Equates Safe Update Class Properties and Global Variables Saved Settings Safe Update Options and Parameters For those that care: the XML Version File Acknowledgements
		Version History
		License & Copyright

 

Introduction

How It Works
Uploading
Downloading
About Digital Certificates

Downloading

The Demo application that ships with SafeUpdate shows you how SafeUpdate works and includes everything you need to get started. It is a good idea to compile the Demo.app file and run the Demo program to get a feel for how safeupdate works.

This Jump Start shows you how to add Safe Update to your application in order to be able to download updates.

Adding Safe Update to your Application.

To add the Safe Update template to your program, add the following to your application's Global Extensions:

1. Activate_NetTalk - Activate CapeSoft's NetTalk.
2. Activate_SafeUpdate - Activate CapeSoft Safe Update.

NOTE: For all the following steps, use single-quotes around the parameters. 

Steps for Downloading

1. Go to the Application | Template Utility menu item and go to Class SafeUpdate - CapeSoft Safe Update. Select ImportSafeUpdateDownloadABC or ImportSafeUpdateDownloadLegacy. Two procedures, called SafeDownload and SafeAutoUpdate will then be added to your application. Note that the names of these procedures must not be changed.
   
   
2. Go to the local extension of your Main() procedure. Add the AutoUpdate - Safe Update Auto Update local extension. This will allow your application to check for updates automatically.
   
   
3. Go to the SafeUpdate Download controls local extension of the SafeDownload procedure. In the Files tab, fill in the URLs of your Update File and the XML version file. The Update File will be the signed file that is the latest version (something like MyApplication_signed.exe), while the XML version file will be something like MyApplication.xml. Make a note of the names that are here, because we'll use these for the uploader later.
   
   
4. Go to the Global Extension Options tab in the global extensions window. Enter the program name and version. The version number can be in any form (1.00.001 or 1.00 beta 2). You'll need to change this with every release of your program (Note - you can use a variable). Take note of this version number - as we'll need it later in the uploader.

Finished!

You've now finished part 1 of 2 (the download)! When your application runs it will check for any updates. However, there are presently no updates because you haven't created or uploaded them. Never mind: Safe Update can do it all for you. Proceed to the Uploading Jumpstart to complete the next step.

Uploading

We've done all the hard work for you in creating an uploader (SafeUp) for your applications. All you have to do is get a digital certificate and learn to use SafeUp and you're done! SafeUp is included with Safe Update as one of the examples and also as an executable. You can find the SafeUpdate Uploader in the SafeUpdate folder in your Start menu under Clarion Accessories, or in your Clarion/3rdparty/bin directory.

You can create your own custom uploader application, either by customising the SafeUp application (which ships as an example with SafeUpdate and can be found in your Clarion/3rdparty/Examples/SafeUpdate directory) or you could write one yourself (templates are provided to do all the hard work for you). See section entitled Creating your own Uploader for more information.

This Jump Start shows you how to get your own digital certificate.

Getting a Digital Certificate

SafeUpdate ships with and example certificate that uses the email address safetester@capesoft.com, which you can use for testing. You should get your own certificate for signing your applications.

A Digital Certificate is needed in order to sign your update file. One of the easier ways of acquiring one is to download it from Thawte.  In the Thawte home page, select the Products menu item and choose Free Personal e-mail certificates. Click on the Click Here link in the first paragraph and follow the prompts.

There are some technical questions that you will be asked that are quite obscure. In the second half of the process, when an e-mail has been sent to you from Thawte, you will be asked what format your certificate should be. Choose "X.509 format". The type of certificate must be for MS Internet Explorer, Outlook and Outlook Express.

When you have finished this section, install your certificate by clicking on the Install Your Cert button. This will put it in the Personal certificate store located in the Current User folder.

Finished!

You should now have your digital certificate installed. For instructions on using SafeUp, click here.

Programmer's Guide

1) I want to add updating to my application
2) I want to check for updates on startup
3) I want to check for updates every couple of days
4) I want the user to be able to check for updates manually
5) I want to use Safe Update to sign and upload my application update file
6) I want to use Safe Update in a Multi-DLL application
7) My application gets sent to the system tray on shutdown. How can Safe Update shut it down properly?
8) Stopping SafeDownload when the application closes
9) How to get your application to find the version embedded inside an XML file
10) I want to generate a version for my application externally
11) I want to create my own Uploader.

For more information, please see the FAQ section.

1) I want to add updating to my application
You will need to follow the Download JumpStart. Some useful information on how Safe Update works can be found in the Introduction in the Reference Manual.

2) I want to check for updates on startup
This option is already enabled by default when you add Safe Update to your application. However, you must make sure the AutoUpdate local extension has been added to your application's main window.

3) I want to check for updates every couple of days
Go to the Global Options Tab and make sure Enable Auto Update is checked. Set Check Every x Days to the interval between update checks. If this is a client application downloading from a server, you can randomize the update time between, say, 01:00 and 03:00. Also make sure the AutoUpdate local extension has been added to your application's main window.

4) I want the user to be able to check for updates manually
Add a control to your window, such as a button or menu item, labelled, for example, 'Check for Updates'. Go to the control's Accepted embed and add the SafeDownload - Start Safe download (new thread) embed.

5) I want to use Safe Update to sign and upload my application update file
Go to the Global Options Tab and make sure the Program Version is a literal string (or is being read from a cwVersionRes file). Now compile your application. As you do this, the XML version file for your application will be automatically generated. Now make your update file as you usually do, using your favourite install-generator, e.g. Wise or Setup Builder.

Finally, you will need to use SAFEUP to sign and upload your update file. SafeUp ships with SafeUpdate and allows you to add as many program to the database of as you like, so you can simply select the application that you want to sign and upload and press one button to do it all for you.

6) I want to use Safe Update in a multi-DLL application
Normally, you would put SafeDownload in the EXE and leave it out of the DLLs. This requires the following options:

1. Do not suppress Nettalk in the root DLL.
2. Add Safe Update and Nettalk to you EXE.
3. Make sure that the options in the Multi-DLL tab in the Safe Update Global Extension are left unchecked.

If you want to generate a root DLL that will allow any program that uses it to update automatically, do the following:

1. Add Safe Update to the DLL, along with Nettalk.
2. Add the ImportSafeUpdateDownload template to the DLL.You'll be able to call SafeDownload from your EXE, since it is globally declared.
3. In the root DLL, check both options in the Multi-DLL tab in the Safe Update Global Extension.
4. Leave Safe Update out of all the other DLLs.
5. Add Safe Update to the EXE, along with Nettalk.
6. In the EXE, check This is part of a Multi-DLL program in the Multi-DLL tab in the Safe Update Global Extension. Also enter the name of the root DLL. 

7) My application gets sent to the system tray on shutdown. How can Safe Update shut it down properly?
You'll have to add your own code in this case. You would probably set a global flag that would tell your application to shut down completely. Add your code to the event:SUshutdown event in your main window. You will need to add the AutoUpdate extension to your main window first.

8) Stopping SafeDownload when the application closes
The way to ensure that SafeDownload has closed is to add the AutoUpdate extension to the application's main procedure.

9) How to get your application to find the version embedded inside an XML version file
See the SafeDownload Procedure documentation on how to do this. 

10) I want to generate a name and version for my application externally
Safe Update can use the version file created by the cwVersionRes - Version Resource global template. The relevant lines from this file are (for example):

PRODUCTVERSION 1,2,3,4
      VALUE "PRODUCTNAME", "My Application\0"

11) Creating your own Uploader

This section shows you how to add Safe Update to your application if you want to write code to sign and upload files.

Adding Safe Update to your Uploader Application.

To add the Safe Update template to your program, add the following to your application's Global Extensions:

1. Activate_NetTalk - Activate CapeSoft's NetTalk.
2. Activate_SafeUpdate - Activate CapeSoft Safe Update.

Some global parameters will need to be changed in order to get Safe Update working, but only after the next steps.

NOTE: For all the following steps, use single-quotes around the parameters if they are literal strings. If they are variables, leave the single quotes off. 

Steps for Uploading

1. Go to the Application | Template Utility menu item and go to Class SafeUpdate - CapeSoft Safe Update. Select ImportSafeUpdateUploadABC or ImportSafeUpdateUploadLegacy. Two procedures, called SafeUpload and SendFTP, will then be added to your application. Note that the names of these procedures must not be changed.
   
   
2. Add the Call Safe Update Upload (new thread) code embed to your application where you want the upload to be called from. 
   
   
3. Fill in the options in the local extension of the SafeUpload Window as follows. In the Files tab, fill in the names of the Update File and the XML version file, including their paths (local or remote). Fill in the version number of the Update File. This will most probably be a variable or an equate.
   
   
4. In the Signature tab enter the name of the Digital Certificate owner. This will be your email address or your name, depending on the type of certificate you own.
   
   
5. Enter the name of the issuer of the digital certificate, or Certificate Authority (CA). This is a part, or all, of the full identity string of the CA. For example, instead of entering the entire string 'Thawte Personal Freemail CA', you could just enter 'Thawte'. Leave the single quotes in. To get the issuer string, see the Certificate Information section

Filling in the Global Parameters
You now need to fill in the options in the Global Extension Options tab. Enter the program name and version of your uploader application. All the other options can be left alone.

Finished!
You're now finished setting up Safe Update for uploading. Reading the Introduction and its associated paragraphs will help you understand the workings of Safe Update better.

The Global Extension

The SafeDownload Control Template
The SafeAutoUpdate Control Template

The SafeUpload Control Template
The SendFTP Control Template

See the Jump Start for information on how to add the Global Extension. The global extension allows you to set the default listbox style for your application.

NOTE: Most of the options shown in the Global Options Tab correspond to user-settable options using the SetOption method in the global SUpdate class.

Global General Tab
Global Options Tab
Global Multi-DLL Tab
Global Save & Load Tab
Global Classes Tab

Downloading

Certificate Information

You will not need to get a certificate if you are only downloading files: the Update File will already have all the necessary certificate information embedded. However, if you want to check the the serial number of the certificate, then reading the following paragraph may be useful.

How to Find the Certificate's Serial Number

SafeUpdate ships with Certificates.msc (Start->Program Files->Clarion Accessories->SafeUpdate->Certificates Manager).
This will launch the Microsoft Certificates Manager (you could also open the file CERTMGR.MSC, which is found in the Windows\system32 directory).

This will display a list of all the certificate stores on your computer. The certificate you require should be in the 'Current User/Personal' store. Go to the Details tab of the certificate and highlight the Serial Number field. The serial number will appear in the lower listbox. You can now cut and paste the serial number into the template, remembering to enclose it in single quotes.

The template makes provision for three different formats of serial number. Examples are:

1. 01 02 03 04 05      (space delimiters)
2. 01:02:03:04:05      (colon delimiters)
3. 0102030405          (no delimiters)

The 2nd format is useful if the certificate is viewed in an Internet browser.

Examples

Demo
Client/Server Demo
Certificate Information

These examples are in your \Clarion\3rdParty\Examples\SafeUpdate directory.

Demo

This is intended to simulate how the uploading and downloading operates. You won't need an FTP site to run the example, since all the files are stored on your PC. However, you will need a Digital Certificate (you can use the certificate that ships with SafeUpdate for testing). See the Upload JumpStart for information on how to get your own certificate for signing your programs.

Take a bit of time to have a look at the Safe Update options that have been set in the DEMO application.

Directory Structure

Inside the demo directory there are two sub-directories:

• .\THEWEB:    Simulates an FTP or web site where the update files are stores.
• .\NEWSAVE:  The directory where the downloaded files are saved before installation.
  

The Applications

There are two applications in this demo. They have been kept as simple as possible (no fancy graphics).

• Demo.APP: The program that is to be updated. This does nothing more than display some help text and an update button. To check for updates for this application, click the relevant button.
  
• Install.APP: This acts as a basic installer program. An explanation of what it does is shown below in step 9. The installer doesn't contain any Safe Update code. A separate installer would not normally be needed if the update file were an EXE file. The installer uses an INI file to specify the source and destination files. This installer is called by SafeUpdate to copy the new update over the old program, then run the new version.
  

How to Make It All Work

Follow these instructions to get the demo working. With version 1.13 we have greatly simplified this, allowing you to easily get the hang of how SafeUpdate works.

1. Compile the Demo.app. This will produce a "version 1.00" demo.exe. This is the program that you run. 
2. If you did not install a certificate when you installed SafeUpdate you will need to install one. The Demo assumes you are using the safetester@capesoft.com certificate for testing.
3. Run the Demo.exe and press the "Check for Update" button.

And that's it! The program downloads and installs a new version, then runs the new version. When it checks for a new version and does the download the signature of the file is checked to ensure that the download is valid.

Explanation

Typically, what you would do to update your program would be to create an EXE file using Wise or another commercial install generator. To keep things simple, this was not done in this demo. This means that the download options in the demo are slightly different to the options you would set if you had used an install generator.

The SafeDownload options for DEMO.EXE are shown in the screenshot below.

SafeDownload options for Demo

In the above screenshot you will notice that the SafeDownload options have the Run Separate Installer option checked (in the Download tab). If you had used an install generator you would check the Run Update After Download option instead. Storing the update file would also be optional.

Client/Server Demo

The client/server demo works the same way as the first demo, but it's twice as much effort to get it running. Safe Update allows your server application to download the client software and store it for the client to upgrade itself later on.

It is recommended that you go through the first demo before you attempt this one, as it is very similar and a little easier.

Directory Structure

The directories are exactly the same as the first demo:

• .\RUNDIR:      The directory where the DEMO program runs.
• .\THEWEB:    Simulates an FTP or web site where the update files are stores.
• .\NEWSAVE:  The directory where the downloaded files are saved before installation.
  

The Applications

There are four applications in this demo. They have been kept as simple as possible (no fancy graphics).

• SERVER.APP and CLIENT.APP: The server and client that is to be updated. These do nothing more than display some help text and an update button. To check for updates for this application, click the relevant button.
  
• SRVSETUP.APP and CLNTSETUP.APP: These act as rather brain-dead installer programs. An explanation of what they does is shown below in step 9. These installers don't contain any Safe Update code. A separate installer would not normally be needed if the update file were an EXE file.
  

How to Make It All Work

Follow these instructions to get the demo working. It looks a bit complex at first, but it should become clear what's going on. Have your digital certificate details handy. Steps 1 to 4 are preliminary and only need to be performed once.

1. Compile all four applications in the Examples\Server directory. 
   
   
2. Copy CLIENT.EXE and SERVER.EXE to the .\RUNDIR directory. This simulates the initial program install.
   
   
3. In the Examples\Server directory you will also see text files called UploadClient.Cfg and UploadServer.Cfg. These is used by SAFEUP to upload the client and server. Open each of these files and edit the line that reads "CertificateAuthority = Thawte" so that the name of your certificate issuer appears after the Equals sign. If you're not sure of the value for this, check the Uploading section of the docs for details.
   
   
4. Put name of the certificate owner in the line "SignedBy = me@mycompany.com". Remove the text '(MODIFY THIS FIELD)'. If you're not sure of the value for this, check the Uploading section of the docs for details.
   
   
5. For each of the client and server applications, go to the Global Extensions and select the Options tab of the Safe Update global extension. Change the version from '1.00' to anything greater, say '2.00'. Recompile the client and server applications. You will notice that files called CLIENT.XML and SERVER.XML have been generated. These were generated by the application called SAFEUP when the applications were compiled. You may now close the Clarion IDE.
   
   
6. To upload the files, run the batch file UPLOADER.BAT. This will silently copy the new version of the client and server to .\THEWEB.
   
   If you look in .\THEWEB you will now see a signed version of the client and server, as well as the signed XML version files CLIENT.XML and SERVER.XML. If you want to have a look at the signature at the end of one of the EXE's, use a binary text viewer. Most of it looks like gibberish, but you'll see the signer name and the Certificate Authority in there somewhere.
   
   That takes care of the preliminaries. The next section is where the actual update takes place.
   
   
7. Go to the .\RUNDIR directory and run the copy of SERVER.EXE. By default, Auto-Update is not enabled so to check for a new version, click the Check for Updates button.
   
   
8. When a new version is detected, it will be downloaded into the .\NEWSAVE directory. The installer will then run and version 2.00 of the server will start automatically. At this stage, only the server has been updated: the client is still at version 1.00.
   
   
9. In the server, click the Check for Updates button again. This will look for a new version of the server. Since no new server version is found it will now check for a new client. When this is found it is downloaded into the .\NEWSAVE directory. A message will pop up telling you that this is the case. This message is not part of Safe Update, but is specific to this example.
   
   
10. Start the client application in the .\RUNDIR directory, which is still version 1.00. Click on the Check for Updates button. This will detect the new version in the .\NEWSAVE directory. The client will then be updated. You will see that its version number has increased.

To create further updates, repeat steps 5 to 10 with different version numbers.

Certificate Information

This is a small application that lets you read the certificate information in any file, even those that have not specifically been signed by Safe Update. See the screen shot below for an example.

Local Extensions

The AutoUpdate Extension

General Tab
Manual Update Tab

This extension adds code that allows your application to:

1. Check for new updates automatically.
2. Shut down after launching an update file. 
3. Check for client updates if this is a server application.

You will normally add it to the first window that opens, e.g. Main(). This extension cannot be added to source or report procedures.

Embed points added by the Auto-update

The Safe Update Template Utility

These templates are at the heart of Safe Update. You will need to load one of these templates into your application in order to download your files. See the JumpStart for more information.

To load the Download template into your application, open the Application | Template Utility menu option and select the ImportSafeUpdateDownload utility (ABC or Legacy), as shown in the picture below. Doing this will create the windows SafeDownload and SafeAutoUpdate, with a Safe Update control template associated with each one. 

Control Templates

The SafeDownload Control Template
The SafeAutoUpdate Control Template

The SafeUpload Control Template
The SendFTP Control Template

The Update Process for client/server applications
The SafeDownload Procedure

The SafeDownload Control Template

This allows you to download files from a remote site using HTTP, or a local site. To add this template, follow the steps shown in the Template Utility section.

Setting the options for this template can be done for a number of configurations:

• A computer connected to the web (no server).
  The path to the files would be a web URL. The user may optionally be prompted to allow downloads and auto-installation. Storage of the download file would be optional.
  
  
• An office network where there is a server looking for web updates.
  The server would download the files from the web to a pre-specified location. No user prompts would be displayed. The global auto-update frequency would be set to a non-zero number of days.
  
  The client would then download the files from the server. User prompts would optionally be displayed, but saving of the files on the client computer would probably not be necessary.

NOTES:  

• The options shown in this section all correspond to user-settable options using the SetOption method in the global SUpdate class. 
  
  
• All boolean options can be assigned a variable by clicking on the Var button in the template extension corresponding to the option (see the pictures below).
  
  
• Safe Update will automatically distinguish between a local and an HTTP path.

SafeDownload General Tab
SafeDownload Files Tab
SafeDownload Downloading Tab
SafeDownload Verification Tab
SafeDownload Client/Server Tab

The update process for client/server applications

SafeDownload General Tab
		The general tab for the SafeDownload template control.

SafeDownload Files Tab
		Update File (SuOpt:MsgdownFilename) The path to the update file. Can be either local or a web URL. XML version file (SuOpt:XMLdownFileName) The path to the version file. Can be either local or a web URL. XML version tag (obsolete) (SuOpt:XMLVersionTag) The version tag string present in the XML file. This is the same variable as the one used in the upload template.

SafeDownload Downloading Tab
		Note: the two screenshots in this table show the boolean variables as constants and the second as variables.  By clicking on a Var button, the corresponding field will change between a check box and a expression field. You'll want to do this if you're setting the options with a runtime variable - but most of the time you'd simply use the checkboxes (i.e. template settings). Ask before getting new version (SuOpt:AskUser) Tick this to allow the user to download the new update now or wait until later. Run update after download (SuOpt:RunFileAfterDownload) Tick this to run the update after download automatically. Run Separate Installer (SuOpt:RunInstaller) Run a separate program to install the Update File. This is useful if the Update File is not an executable. This option is not available if the Update File is to be run. Installer Program (SuOpt:Installer) The installer to run. Ask before running update (SuOpt:AskBeforeInstall) Tick this to give the user a choice whether to run the update now or later. Store file after download (SuOpt:StoreFileAfterDownload) Tick this to save a copy of the new update. Keep signature attached (SuOpt:KeepSignature) Tick this to save the file with the signature still appended. This should only be done if the file is to be opened with a program that recognises digital signatures. Get location from user (SuOpt:UserSaveLocation) Tick this to prompt the user for a path where the update file will be saved. Storage location (SuOpt:StoreLocation) Default location to store the update file. Turn caching off (SuOpt:CacheOff) Bypass your network's cache and download directly from the http server. Useful if an older version of your application is in the cache. Hide the file path details while downloading The download window will show a generic message instead of the file URL. This is good if you don't want to reveal your file's path.
	Tab shown with no Var buttons checked.
	Tab shown with all Var buttons checked.

SafeDownload Verification Tab
		Note: the two screenshots in this table show the boolean variables as constants and as variables.   Verify the file signatures (SuOpt:VerifyFiles) Tick to verify the file signatures. Must be signed by (SuOpt:MustBeSignedBy) The owner of the certificate, i.e. your name or your e-mail address. Cert. Authority (SuOpt:CertProviderDown) Who issued the certificate, e.g. Thawte, Verisign, etc. Cert. Serial Number (SuOpt:SerialNumber) The certificate serial number. Entering this is optional, Entering it provides extra security against bogus certificates. Details of how to find the serial number are given in Certificate Information. Errors to check (SuOpt:CertFailures) If any of these errors is selected, then if the error occurs in the certificate an error will occur and the update will not be installed. Their bit positions in SuOpt:CertFailures are shown in the Signature Errors table. Note: it is not recommended that the No Issuer Certificate option is checked unless the user must have a certificate by the issuer of your certificate present on their machine. Action if signature fails (SuOpt:NotSignedOption) There are four different actions that can be taken if an error occurs in one of the signatures: these are described in the Downloading and Verification Options table.
	Tab shown with no Var buttons checked.
	Tab shown with all Var buttons checked.

SafeDownload Client/Server Tab
		This is a server application Tick this option if: this application is the server part of a client/server system and  you want it to check for and download the latest client update automatically. Note that this can be a variable, for use in, e.g, peer-to-peer applications. See the description below this table for what happens and what options must be set. If you aren't sure what client/server is all about, just ignore this tab. Update file The name and path of the client update file. Version file The name and path of the client version file. Install path Where you want the client update file to be stored. This path is where the client will look for its update and version files.

The update process for client/server applications

If the 'This is a server application' option is checked in the Client/Server Tab, the following steps must be performed.

Server application options

1. The Enable Auto-update option in the Options Tab of the global extension must be enabled.
   
   
2. The Safe UpdateAuto-update extension must be added to your main procedure and the server option must be checked.
   
   
3. The 'Store the file after download' option in the Download Tab must be enabled and a path specified.

Client application options

1. Make sure that the file path entered in the Files Tab in the SafeDownload extension is the same one you entered in the Install Path field in the server's Client/Server tab. You could get around this by sending a message from the server to the client with the path as part of the message.
   
   
2. Verify the File Signatures must be disabled in the SafeDownload Verify tab, since the server removed the signature when it downloaded the update file.

Client/Server update process

1. The server checks it's version. If a new version is found, the server is updated in the usual way.
   
   
2. If no new version of server is found, the server compares the client's version file on the web with the existing one, stored in the client Install Path (Client/Server tab option).
   
   
3. If a new version of client is found, it is downloaded and stored in the Install Path specified in the Client/Server Tab.
   
   
4. If you need to upgrade your clients immediately, you can then send them a message to inform them that they need to upgrade. This would be added at the %SafeSendMessageToClients embed in your main procedure. The client would then call SafeDownload. In your message to the clients you could also send the path to the update file. If you did this, you would have to specify the install path as a global variable and set its value before the client called SafeDownload.

The SafeDownload Procedure

SafeDownload (string pHideWindow, string pXMLfile, string pVerify)

Description:
Download and run an Update File, first checking the XML version file to see if the update is newer than the existing application. 

SafeDownload can also be used to find the version embedded in any XML file. This might be used in a client / server application. For example, when a client accesses the server, the server would examine the version of the client somehow. If the client were not up to date, the server would then send a message telling the client to request an update. When finding the version of a non-default XML file, the Update File is not downloaded. 

To retrieve the version of an XML file (default or non-default

When SafeDownload closes, the XML file version is placed in the SuOpt:AcquiredVersion parameter. An event:SUactivatewindow event is also sent to the window that started SafeDownload. You can read the version by embedding code at this point. This embed point will already be present if the window has the SafeAutoUpdate template added. Otherwise you will have to add it yourself. See the example below.

NOTE: Only one copy of SafeDownload can be run at one time.

Parameters:
pHideWindow: Set this to '1' to hide the window. Set it to '0' to show the window. Notice that it is a string parameter.

pXMLfile: This is used when you want to find the version embedded in an XML file that is not the default XML file. If you are finding the version of the default XML file, this parameter can be set to an empty string.

pVerify: Set to '0' to disable signature verification and '1' to enable it. Notice that it is a string parameter. This parameter is used in conjunction with pXMLfile. If pXMLfile is an empty string, this parameter has no effect but must be included anyway.

Return value: none.

Example (ABC):

  In TakeAccepted()
    ....
  !-- Start SafeDownload.
  of ?ButtonDownload
     start (SafeDownload, '1', 'www.mycompany.com/ClientApp.xml', '1')

  In TakeWindowEvent()
    ....
  !-- SafeDownload ended.
  of event:SUactivatewindow
    MyVersion = gSUpdate.GetOption (SuOpt:AcquireVersion)
 

SafeDownload Screen Shots
		Searching for the XML version file.
		Asking to download the Update File.
		Asking to install the Install the Update File.

The SafeAutoUpdate Control Template

If Auto-Update has been enabled, SafeAutoUpdate checks for updates as often as you have specified. SafeAutoUpdate runs in its own thread and is terminated when the main application procedure shuts down.

This extension can be left out if auto-updating is not required. To add this template, follow the steps shown in the Template Utility section.

SafeAutoUpdate General Tab
		The general tab for the SafeAutoUpdate template control. Show the AutoUpdate Window Check this option to display the SafeAutoUpdate window. Show the SafeDownload Window Check this option to display the SafeDownload window when Auto-updating.

SafeAutoUpdate ScreenShot

Code Embeds

Start Safe Download
Save all the INI File Settings
Get an INI File Setting
Save an INI File Setting

Start Safe Download

This embed calls SafeDownload. It can be attached to the Accepted event of a button or a menu item, for example, in order to start the download process. Choose the embed as shown in the picture below.

If downloading is enabled, the following dialog box will appear:

In the event of your wanting to embed this at the start of your program, check the button. If you want to show the update only some of the time, make the option variable by clicking on the Var button. The window will change to look like the figure below. Enter your own variable in the space provided.

If downloading has been disabled in the Global Extension, the following dialog box will appear:

Save all the INI File Settings

This saves all the Safe Update settings, as listed in Saved Settings. You would add this code when the user changes one or more of the saveable settings. Select this from the Embeds window.

Get an INI File Setting

Read an INI file or registry setting. This is actually done indirectly, from the global SUpdate class. The code embed asks for the setting name and the variable that it will be stored in, as shown in the figure below.

Save an INI File Setting

Save an INI file or registry setting. The setting is stored in the global SUpdate class and also in the INI file or registry. The code embed asks for the setting name and the value that will be stored, as shown in the figure below.

Uploading

Certificate Information

You will not need to get a certificate if you are only downloading files. The Update File will already have all the necessary certificate information embedded. If this applies to you, then you can safely skip this section.

How do I get a Certificate?

The Upload Jump Start section has information on how to do this.

Certificate Requirements

The certificate needs to:

• Be issued by a Certificate Authority, e.g. Thawte. See the Upload JumpStart section for more information on how to obtain one.
  
  
• Have a private key attached. You can see if this is the case by viewing the certificate (described how in the next paragraph). At the bottom of the General tab you will see the text 'You have a private key that corresponds to this certificate.' if a private key is present. See the picture below.

How to Find the Certificate's Serial Number

If you have a copy of the certificate, simply open the file. Alternatively, you can view the certificate information in Internet Explorer: In your Tools - Internet Options - Content, click the Certificates button and you will see a list of certificates. Double click on the correct one to give you the details for that certificate.

Otherwise you will need to open the file CERTMGR.MSC. This is found in the Windows\system32 directory. The certificate you require should be in the 'Current User/Personal' store. Go to the Details tab of the certificate and highlight the Serial Number field. The serial number will appear in the lower listbox. You can now cut and paste the serial number into the template, remembering to enclose it in single quotes.

The template makes provision for three different formats of serial number. Examples are:

1. 01 02 03 04 05      (space delimiters)
2. 01:02:03:04:05      (colon delimiters)
3. 0102030405          (no delimiters)

The 2nd format is useful if the certificate is viewed in an Internet browser.

How do I find the Issuer Name?

Click on the Certification Path tab, in which you will see a tree of certificates. Select the item that is second from the bottom of the tree and click the View Certificate button. Now click on the Details tab and select the Issuer field. The CN field (in the lower list box) is the issuer name. See the screenshot below for an example.

An Uploader Example (SAFEUP)

This is a simple uploader program that allows you to generate XML files, as well as sign and upload your update files. SAFEUP mirrors the options found in the SafeUpload local extension: therefore all the options that are used in SAFEUP are exactly the ones used in the SafeUpload local extension. The SAFEUP screenshot is shown below.

SAFEUP is a complete uploader and can be used without any modifications. It comes with source code so you can see 'under the hood'. The binary SAFEUP.EXE is distributed with Safe Update and can be found in the Clarion\3rdParty\bin directory.

You only need one Uploader for all your SafeUpdated programs. You can enter a record for each one in the list using the details that you entered into the Download Jumpstart as follows:

Command Line Mode and Configuration Files
SAFEUP can also be used from the command line using a configuration file. A README file which shows the format of the configuration file is supplied with SAFEUP. A configuration file example is also shown at the end of this section. When used with a configuration file, SAFEUP runs hidden.

There are some constraints in the syntax of the config file:

• The parameter names must not be changed. However, they are case-insensitive.
• Each parameter and value must be on its own line.
• The configuration file must be no larger than 8 kB.

These are the things you are allowed to do in the file:

• The order of the parameters in the file doesn't matter.
• Parameter values can be left blank if you don't want them set, or the config line can be left out altogether.
• Empty lines are allowed between parameters.
• Single quotes are allowed around the values.
• Comment lines are allowed, so long as none of the parameter names are present in the comment. There is no format constraint for a comment.

If there is an error in one of the lines of the configuration file, the line is ignored. However, processing of the configuration file will continue until the end of the file.

Example Configuration File
An example configuration file is shown in the figure below. You can copy the text in this figure to create your own configuration file. The top four parameters are task options.

The colour of the other parameters show their dependencies on the task options. The black parameters depend on more than one task option.

The SAFEUP Command Line
Run the application with the following parameters:

  uploader [-E] <configfile>

where the parameters are defined as follows:

Note: The demo and pre-compiled versions of SAFEUP include CapeSoft File Manager 2 (FM2) in order to track the changes of the dictionary file. FM2 was not included in the examples because it is not needed with Safe Update. If you have FM2 or FM3, feel free to add it to the SAFEUP example.

Further Information

The Programmer's Guide has more useful information on how to use SAFEUP for signing and uploading.

The Safe Update Template Utility

These templates are at the heart of Safe Update. You will need to load one of these templates into your application in order to upload your files. See the JumpStart for more information.

To load the Upload template into your application, open the Application | Template Utility menu option and select the ImportSafeUpdateUpload utility (ABC or Legacy), as shown in the picture below. Doing this will create the windows SafeUpload and SendFTP, with a Safe Update control template associated with each one. 

Control Templates

The SafeUpload Control Template
The SendFTP Control Template

The SafeUpload Control Template

This allows you to upload a signed Update File and XML version file to either a remote site using FTP, or local site. To add this template, follow the steps shown in the Template Utility section.

To hide the update process, go to the SendFTP window extension and tick the Hide option.

NOTE:  

• The options shown in this section all correspond to user-settable options using the SetOption method in the global SUpdate class.
  
  
• All boolean options can be assigned a variable by clicking on the Var button in the template extension corresponding to the option (see the pictures below).
  
  
• Safe Update will automatically distinguish between a local and an FTP path.

SafeUpload General Tab
SafeUpload Files Tab
SafeUpload Signature Tab
SafeUpload Uploading Tab 

SafeUpload General Tab
		The general tab for the SafeUpload template control.

SafeUpload Files Tab
		Note: the two screenshots in this table show the boolean variables as constants and as variables.   Update File (SuOpt:UpdateUpFileName) The name of the Update File to be uploaded, including local path information. NOTE: If this field is left blank, no signing or updating is done for the update file. XML version file (SuOpt:XMLupFileName) The name of the XML version file to be uploaded, including local path information. NOTE: If this field is left blank, no signing or updating is done for the XML file. Automatically generate XML (SuOpt:CreateVersionFile) Allow Safe Update to generate the version file when checked. This is the recommended setting. Version (SuOpt:Version) The version of the file being uploaded. This string is added to the XML file. The version can be of any format, so long as it is fewer than 40 characters long. XML version tag (SuOpt:XMLVersionTag) The tag that will identify the version inside the XML file. Set to 'version' by default.
	Tab shown with no Var buttons checked.
	Tab shown with all Var buttons checked.

SafeUpload Signature Tab
		Note: the two screenshots in this table show the boolean variables as constants and as variables.   Sign the files (SuOpt:SignFiles) Tick to enable signing of the files. Signed by (SuOpt:SignedBy) The signer name on your personal certificate. Certificate Provider (SuOpt:CertProviderUp) Issuer of the certificate. This may be left blank. If this is the case, then the latest certificate signed by you is used. Cert. Serial Number (SuOpt:SerialNumber) The certificate serial number. Entering this is optional. Details of how to find the serial number are given in Certificate Information.  Warning: the certificate's serial number will change if you re-install your certificate so beware! Append to file name (SuOpt:AppendToUpdate) Append a suffix to the signed update file name. This allows you to sign a copy of the update file. If you want the original file signed, leave this field blank.
	Tab shown with no Var buttons checked.
	Tab shown with all Var buttons checked.

SafeUpload Uploading Tab
		Note: the two screenshots in this table show the boolean variables as constants and as variables.   Upload the files (SuOpt:UploadFiles) Tick this option to enable uploading of the files. Use external app to upload (SuOpt:UploadUsingOther) Tick this if you want to use a 3rd party upload program rather than SafeUpload. Command line (SuOpt:UploadProg) The command line used to call the 3rd party upload program. Server (SuOpt:FTPserver) Name of the FTP server. User (SuOpt:FTPuser) Your FTP user name. Password (SuOpt:FTPpassword) The user password. Update file directory (SuOpt:FTPMsgDirectory) Where the Update File will be stored. This can also be a local path. XML file directory (SuOpt:FTPXmlDirectory) Where the XML version file will be stored. This can also be a local path. Unsigned Update Dir (SuOpt:FTPUnsignedDirectory) Where the unsigned update file will be stored. This can also be a local path. Note: if this field is left blank, the unsigned update file will not be uploaded.
	Tab shown with no Var buttons checked.
	Tab shown with all Var buttons checked.

Why you may need signed and unsigned versions

When the user buys and downloads your application for the first time they would have no means of removing a signature attached to the setup file. Removing the signature is sometimes necessary because setup files created with some programs, such as Wise, perform self-checks to see if they've been modified. A signature is obviously a modification, so the setup file will not run.

It is not always the case that self-checking is performed, however. For example, Setup Builder allows you to turn checking off. In this case a separate unsigned file would not be necessary.

In summary, you will need to upload an unsigned version if the setup file generator doesn't allow you to disable the self-check feature. This is the case with Wise, but not Setup Builder.

If you h