TTMSFNCAppUpdate

TTMSFNCAppUpdate is a non-visual component to manage automatic application updates through HTTP requests.

The application update process happens in several steps:

1. Obtaining the control file (.INF) from an HTTP/HTTPS based location.
2. Processing of the .INF file by verifying new files, new versions and downloading the necessary update files.
3. Extracting the new versions where necessary and restarting the application if needed.

TTMSFNCAppUpdate is NOT compatible with mobile and WEB platforms. Supported desktop platforms are:Windows, macOS, Linux.

Setting the update distribution location

Set the URL property to where the .INF file is located.

If the update is located on a password protected website (via HTTPS), you can use the Username and Password properties for HTTP authentication. If Username and Password properties are left empty, no HTTP authorization header will be added to the request.

procedure TForm1.FormCreate(Sender: TObject);
begin
  TMSFNCAppUpdate1.URL := 'http://my.website.com/distribution/update.inf';
  //Set only if HTTP authentication is needed
  TMSFNCAppUpdate1.Username := 'Username';
  TMSFNCAppUpdate1.Password := 'password';
end;

Controlling the update process

The full update process is started by calling TTMSFNCAppUpdate.DoUpdate.

If only a check is required to see the availability of a new version, use the TTMSFNCAppUpdate.NewVersionAvailable: Boolean function.

NewVersionAvailable will not only download but also parse the contents of the update control file. After the function returns, the public TTMSFNCAppUpdate.FileList collection property and the TTMSFNCAppUpdate.AppInfo property will be filled with the contents of the update control file. From there, you can freely manipulate each file desctiption before proceeding with the update.

To proceed with the update after calling NewVersionAvailable, use TTMSFNCAppUpdate.StartUpdate. This will use the TTMSFNCAppUpdate.FileList property to download each file where the version requirements are met. After the ZIP files are downloaded, they will be extracted to the marked location (see Control file for more info), replacing the old files.

procedure TForm1.Button1Click(Sender: TObject);
begin
  if TMSFNCAppUpdate1.NewVersionAvailable then
  begin
    if TMSFNCAppUpdate1.FileList.Count > 0 then
      TMSFNCAppUpdate1.FileList[0].URL := 'newdownloadurl';

    TMSFNCAppUpdate1.StartUpdate;
  end;
end;

Once the update has finished, the application will restart automatically unless the OnAppRestart event is implemented.

procedure TForm1.TMSFNCAppUpdate1AppRestart(Sender: TObject;
  var Allow: Boolean);
begin
  //This blocks the restarting of the application
  //Keep in mind that the the files are already replaced at this point
  //The next time the application is started, the new version will launch
  Allow := False;
end;

TTMSFNCAppUpdateFile

After TTMSFNCAppUpdate.NewVersionAvailable is called, the FileList property will be filled with the contents of the update file descriptions. The FileList property contains TTMSFNCAppUpdateFile items.

Property name	Description
Active	By default always True. If set to False, the file download will be skipped regardless of the new version/checksum/size.
AppUpdate	Corresponds to the appupdate keyword from the update control file.
CheckSum	Corresponds to the newchecksum keyword from the update control file.
Description	Corresponds to the descr keyword from the update control file.
FileSize	Corresponds to the filesize keyword from the update control file.
FileVersion	Corresponds to the newfileversion keyword from the update control file.
LocalVersion	Corresponds to the localversion keyword from the update control file.
Mandatory	Corresponds to the mandatory keyword from the update control file.
RestartMessage	Corresponds to the restartmessage keyword from the update control file.
Size	Corresponds to the newsize keyword from the update control file.
TargetDir	Corresponds to the targetdir keyword from the update control file.
URL	Corresponds to the url keyword from the update control file.
Version	Corresponds to the newversion keyword from the update control file.

Control file

The update control file is an .INI organized file to control the update. The general structure of an update control file as follows:

[update_platform]
keywords

[files_platform]
count=N

[file1_platform]
keywords

…

[fileN_platform]
keywords

In this structure the platform suffix should always correspond to the target platform:

• win for Windows
• macos for macOS
• linux for Linux

The TTMSFNCAppUpdate component will automatically scan the control file for the platform it is running on. This way a single control file can be used to handle the updates for the 3 supported platforms at the same time.

Update section

In the [update_platform] section the following keywords are supported:

Keyword	Description
newversion	Major,minor,release,build (, or . separated). The value of newversion will be always compared to the TTMSFNCAppUpdate.NewVersion property. In this case there is no need to point to a local file.
newfileversion	Major,minor,release,build (, or . separated) The value of newfileversion will be compared to the file version of the file specified by localversion. Linux platforms do not support file versions.
newchecksum	Integer value. The value of newchecksum will be compared to the CRC32 checksum of the file specified by localversion.
localversion	To be used in combination with newfileversion or newchecksum.
whatsnew	Location of a “What’s new?” file. It will be extracted into the TTMSFNCAppUpdate.AppInfo.WhatsNew property.
eula	Location of an “EULA” file. It will be extracted into the TTMSFNCAppUpdate.AppInfo.EULA proprety.
showurl	An URL that can be shown by the developer. It will be extracted into the TTMSFNCAppUpdate.AppInfo.URL property.
query	Query string allowing the user to cancel the update. If TTMSFNCAppUpdate.DoUpdate is called, this will be automatically displayed if not empty. It will be extracted into the TTMSFNCAppUpdate.AppInfo.UpdateMessage property.

Files section

The number of new files are defined in the [files_platform] section with the count keyword.

For example, an update distribution of 3 files for linux:

[files_linux]
count=3

File section

The [filesN_platform] sections contain the details of each update file.

Supported keywords are:

Keyword	Description
newversion	The value of newversion will be always compared to the TTMSFNCAppUpdate.NewVersion property.
newfileversion	The value of newfileversion will be compared to the file version of the file specified by targetdir + localversion. Linux platforms do not support file versions.
newsize	The value of newsize will be compared to the file size of the file specified by targetdir + localversion.
newchecksum	The value of newchecksum will be compared to the CRC32 checksum of the file specified by localversion.
url	The URL from which the update file will be downloaded. The file should always be a ZIP compressed file.
localversion	Defines the local file to be updated.
targetdir	Defines in which directory the local file is located. If empty, the currect directory will be used.
appupdate	Cam be optionally set to 0 or 1. 1 means that in case the file is used in the update, the application will be restarted.
params	Command line parameters to be used with the application when it is restarted at the end of the update process.
restartmessage	If used and non-empty, this message will be displayed in a confirmation dialog.
mandatory	Can be optionally set to 0 or 1. 1 means that the file is mandatory for the update process.
descr	Description of the file.
filesize	Can be optionally set. This can be used to calculate the total file size used during progress indication.

If no newversion, newfilesize, newsize or newchecksum keywords are present the udpate file will always be downloaded.

The targetdir determines in which folder the localversion file is located. If left empty, the current directory will be used. There are predefined prefixes that will be automatically replaced by the correct path depending on the target platform. These prefixes are:

• {WIN} – Windows folder (Windows only)
• {SYS} – Windows System32 folder (Windows only)
• {SYSWOW64} – Windows SysWOW64 folder (Windows only)
• {PF} – Program files folder (Windows only)
• {APP} – Application folder
• {TMP} – Temporary files folder
• {DOC} – Documents folder
• {HOME} – Home/user folder

Implementing the OnConvertPrefix event allows to use custom prefixes in addition to the predefined prefixes.

Complete control file example

[update_win]
newfileversion=1.1.0.0
localversion={APP}\Demo.exe

[files_win]
count=2

[file1_win]
newfileversion=1.1.0.0
url=https://download.tmssoftware.com/fncapptools/appupdate/AppUpdateDemo_win.zip
localversion=Demo.exe
appupdate=1

[file2_win]
newsize=1961
url=https://download.tmssoftware.com/fncapptools/appupdate/AppUpdateDemo_data.zip
localversion=app_icon.png

[update_macos]
newfileversion=1.1.0
localversion={APP}/Demo.app

[files_macos]
count=2

[file1_macos]
newfileversion=1.1.0
url=https://download.tmssoftware.com/fncapptools/appupdate/AppUpdateDemo_mac.zip
localversion=Demo.app
appupdate=1

[file2_macos]
newsize=1961
url=https://download.tmssoftware.com/fncapptools/appupdate/AppUpdateDemo_data.zip
localversion=app_icon.png

Debugging

In case something is not working as desitred, it is often convenient to check what steps were executed. This can be straced by setting the TTMSFNCAppUpdate.Logging.Enabled property to True. During execution TTMSFNCAppUpdate will create a log file with a default name in the temporary files folders. If the file path should be different from the default, it can be set through the TTMSFNCAppUpdate.Logging.FileName property. The TTMSFNCAppUpdate.Logging.FileName property also accepts {PREFIXES} as detailed above.

Properties

Property name	Description
AppInfo	Property which holds data from the [update_platform] section. These are WhatsNew, EULA, URL and UpdateMessage.
Elevate: Boolean	For Windows only. If set to True, it always asks for administrator rights and applies the update in an elevated process.
FileList	A collection of update file descriptions. Filled after NewVersionAvailable is called.
Logging	If Logging.Enabled is True, the component will produce a log file. This file is saved to the temporary files folder by default. If Logging.FileName is not empty, it will be used for the log file.
NewVersion: string	For component based version comparasion for application update.
URL: string	The URL on which the update control file is located.
Username: string	If the update is located on a protected website (via HTTPS), the username can be set with this property. If left empty, no HTTP authorization header will be added to the request.
Password: string	If the update is located on a protected website (via HTTPS), the password can be set with this property. If left empty, no HTTP authorization header will be added to the request.

Methods

Method name	Description
DoUpdate	Starts the automatic update process. It will check for new versions, update and restart the application.
NewVersionAvailable	Can be used to check if there are any new versions before updating. After NewVersionAvailable is called, the FileList property will be filled with the contents of the update file descriptions.
StartUpdate	Proceed with updating after NewVersionAvailable has been called.

Events

Event name	Description
OnAppDoClose	Even triggered to allow the application to execute its own close method, otherwise TTMSFNCAppUpdate will force an application close itself.
OnAppRestart	Event triggered before restarting the downloaded version. Set Allow to False if restarting the application is not allowed.
OnControlFileDownloaded	Event triggered when the control file finished downloading.
OnConvertPrefix	Event triggered to allow users to convert directory prefixes into directories on the system.
OnFileDownloaded	Event triggered when an update file finished downloading. The StatusCode can be used to determine if the download was successful.
OnFileProgress	Event triggered for the file download progress indication. Pos holds the position of the download in a file of size set by the Size parameter.
OnFileNameFromURL	Event triggered to allow dynamically changing a download filename to another filename. If the URL would be http://myserver.com/myfile.zip, the download will automatically be named myfile.zip. By using the OnFileNameFromURL event, tis can be dynamically renamed to another filename.