Skip to content

autoUpdate

This class allows managing automatic application updates through HTTP requests.

import { autoUpdate } from 'miletus';

autoUpdate.on('update-available', () => {
    alert('New version available');
}

autoUpdate.setUpdateURL('URL_to_control_file');
autoUpdate.checkForUpdates();

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.

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.

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

During update the control file for the platform it is running on will be automatically scanned. 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
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.

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
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.
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.

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

Debugging

In case something is not working as desitred, it is often convenient to check what steps were executed. This can be traced by enabling the logging before doing any update related calls.

appUpdate.enableLogging(true);

During execution the application 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 fileName optional parameter. The fileName parameter also accepts {PREFIXES} as detailed above.

Methods

setUpdateURL(url)

  • url string - The URL of the control file.

Sets the URL for the control file.

checkForUpdates([user, password])

  • user string (optional) - Username for HTTP authorization.
  • password string (optional) - Password for HTTP authorization.

Checks the control file to see if there are updates available.

startUpdate([user, password])

  • user string (optional) - Username for HTTP authorization.
  • password string (optional) - Password for HTTP authorization.

Starts the application updating.

finishAndRestart()

Can be used to restart the application after the updates were applied.

enableLogging(enable[, fileName])

  • enabled boolean - Boolean value to enable or disable logging.
  • fileName string (optional) - Path to the log file.

Enables the logging for the update process. Call this before checking for updates or starting the update.

Events

'update-available'

Event triggered when an update is available after calling checkForUpdates().

'update-unavailable'

Event triggered when there are no updates available after calling checkForUpdates().

'update-finished'

Event triggered when the application update has finished. At this point it is advised to restart the application as a new version has already replaced the old version. The application can be restarted by calling finishAndRestart().