AUpdater Class Reference

Updater class. More...

#include <AUI/Updater/AUpdater.h>

Detailed Description

Warning

This API is experimental. Experimental APIs are likely to contain bugs, might be changed or removed in the future.

AUpdater follows strategy pattern, i.e., you are excepted to call its functions but the behaviour and conditions are yours.

Refer to aui::updater for update process overview.

Member Function Documentation

> All members, including inherited

applyUpdateAndRestart()

virtual void AUpdater::applyUpdateAndRestart ( )

virtual

Basically about replacing files (no network operations will be performed).

Requires status = StatusWaitingForApplyAndRestart, otherwise has no effect.

Terminates current process with std::exit(0)

Debugging update deployment#

You can locate update deployment logs by locating deployment process id (pid). The PID is printed by this function:

[06:49:33][UI thread][AUpdater][INFO]: applyUpdateAndRestart: started process pid=3708325, exe=...

Log files location are printed in the beginning of every AUI-based programs (if they use ALogger):

[06:49:14][UI thread][Logger][INFO]: Log file: /tmp/aui.3707546.log

You can now locate the log file by using subprocess' PID printed earlier:

cat /tmp/aui.3708325.log
[06:49:33][UI thread][Logger][INFO]: Log file: /tmp/aui.3708325.log
[06:49:33][UI thread][AUpdater][INFO]: --aui-updater-wait-for-process: 3707546 exited with 0
[06:49:33][UI thread][AUpdater][INFO]: deploying update: /tmp/__aui_update_example_app/download -> /home/...
[06:49:33][UI thread][AUpdater][ERR]: Can't deploy update, trying to launch original: ...
 - at 0x5555558f3aae aui_entry(AStringVector const&)(main.cpp:9)
 - at 0x5555556b0028 aui_main(int, char**, int (*)(AStringVector const&))(OSDesktop.cpp:160)
 - at 0x7ffff7261248(?:0)
 - at 0x7ffff726130b(?:0)
 - at 0x555555654195(?:0)
Caused by: (AIOException) AFileOutputStream: could not open /home/...: Text file busy
 - at 0x5555556c0443 aui::impl::lastErrorToException(AString)(ErrorToExceptionImpl.cpp:21)
 - at 0x55555568ec97 AFileOutputStream::open(bool)(AFileOutputStream.cpp:67)
 - at 0x55555568ed44 AFileOutputStream::AFileOutputStream(AString, bool)(AFileOutputStream.cpp:24)
 - at 0x5555556964a2 APath::copy(APath const&, APath const&)(APath.cpp:291)
 - at 0x555555641585 AUpdater::deployUpdate(APath const&, APath const&)(AUpdater.cpp:267)
 - at 0x5555558fb2ff AUpdater::handleStartup(AStringVector const&)(AUpdater.cpp:76)
 - at 0x5555558f3aae aui_entry(AStringVector const&)(main.cpp:9)
 - at 0x5555556b0028 aui_main(int, char**, int (*)(AStringVector const&))(OSDesktop.cpp:160)
 - at 0x7ffff7261248(?:0)
 - at 0x7ffff726130b(?:0)
 - at 0x555555654195(?:0)

checkForUpdates()

void AUpdater::checkForUpdates

(

)

Requires status = StatusIdle, otherwise has no effect.

deployUpdate()

virtual void AUpdater::deployUpdate ( const APath & source, const APath & destination )

protectedvirtual

Called in newly downloaded executable.

downloadAndUnpack()

void AUpdater::downloadAndUnpack ( AString downloadUrl, const APath & unpackedUpdateDir )

protected

Called by downloadUpdateImpl. Updates AUpdate::status progress.

downloadUpdate()

void AUpdater::downloadUpdate

(

)

An implementation might expect to checkForUpdates to be called first.

downloadUpdateImpl()

virtual AFuture< void > AUpdater::downloadUpdateImpl ( const APath & unpackedUpdateDir )

protectedpure virtual

Parameters

unpackedUpdateDir

location to unpack an update to.

Typically implemented as download to temporary dir and unpacking the archive to the specified unpackedUpdateDir.

Unpack your application files to unpackedUpdateDir. AUpdater is responsible for cleaning this dir in the future.

getInstallationDirectory()

virtual APath AUpdater::getInstallationDirectory ( const GetInstallationDirectoryContext & context )

protectedvirtual

Default implementation guesses installation directory based on

getModuleName()

virtual AString AUpdater::getModuleName ( ) const

protectedvirtual

Default implementation determines module name using AProcess::self().

The module name is used to construct temporary directory and locate an executable in a downloaded portable.

getUnpackedUpdateDir()

virtual APath AUpdater::getUnpackedUpdateDir ( ) const

protectedvirtual

The dir persists between different launches.

handlePostUpdateCleanup()

virtual void AUpdater::handlePostUpdateCleanup ( )

virtual

Default implementation deletes AUpdater::getUnpackedUpdateDir() dir.

handleStartup()

virtual void AUpdater::handleStartup ( const AStringVector & applicationArguments )

virtual

Parameters

applicationArguments

arguments to your program.

The arguments starting with --aui-updater are should be ignored by your application.

Performs autoupdate-specific routines on startup of your application. In best scenario, this function should be called by your application as early as possible.

This function might terminate current process with std::exit(0), in case of performing autoupdate routines.

This function will attempt to restore InstallCmdline state (StatusWaitingForApplyAndRestart) via AUpdater::loadInstallCmdline. If the latter succeeds, AUpdate::triggerUpdateOnStartup is called to perform on-startup update.

This function handles following arguments to your application:

• --aui-updater-origin -
• --aui-updater-wait-for-process - maps to AUpdater::handleWaitForProcess that instructs AUpdater to wait the specified process to finish before processing next argument(s).
• --aui-updater-cleanup - maps to AUpdater::handlePostUpdateCleanup and returns control flow to normal execution of your application (last updating step)
• --aui-updater-failed - reports last error occurred while update deployment. See AUpdater::getLastDeploymentError().

Refer to aui::updater for update process overview.

isAvailable()

static bool AUpdater::isAvailable ( )

static

For cases when AUpdater is available see aui::updater

loadInstallCmdline()

virtual AOptional< InstallCmdline > AUpdater::loadInstallCmdline ( ) const

protectedvirtual

AUpdater::handleStartup will try to restore the state via loadInstallCmdline. If InstallCmdline is successfully restored, AUpdater immediately triggers update routine with triggerUpdateOnStartup which exits the application.

The implementation must ensure that subsequent startups would not trigger on-startup update to avoid endless loops in case of failure, i.e, by deleting a file.

See also

triggerUpdateOnStartup

saveCmdline

makeDefaultInstallationCmdline()

InstallCmdline AUpdater::makeDefaultInstallationCmdline ( ) const

protected

By default, installerExecutable is a copy of your application executable. The installation process is triggered via special arguments in installerArguments.

reportDownloadedPercentage()

void AUpdater::reportDownloadedPercentage ( aui::float_within_0_1 progress )

protected

Requires status = StatusDownloading, otherwise has no effect. Updates the value in UI thread.

reportReadyToApplyAndRestart()

void AUpdater::reportReadyToApplyAndRestart ( InstallCmdline cmdline )

protected

See also

saveCmdline

applyUpdateAndRestart

saveCmdline()

virtual void AUpdater::saveCmdline ( const InstallCmdline & cmdline ) const

protectedvirtual

See also

loadInstallCmdline

triggerUpdateOnStartup()

virtual void AUpdater::triggerUpdateOnStartup ( )

protectedvirtual

The function is called by AUpdater::handleStartup. If triggerUpdateOnStartup succeeds, it should terminate execution of the current process.

Requires status = StatusWaitingForApplyAndRestart.

If you'd like to disable applying downloaded update on startup, stub this function.

Member Data Documentation

status

AProperty<std::any> AUpdater::status

Status of the AUpdater to observe from outside, i.e., by UI.

status is updated in UI thread only.

status is designed in such a way the user can use their own custom status types or any of predefined ones:

• AUpdater::StatusIdle
• AUpdater::StatusCheckingForUpdates
• AUpdater::StatusDownloading
• AUpdater::StatusWaitingForApplyAndRestart
• AUpdater::StatusNotAvailable

These statuses might be set by AUpdater itself.

Typical observer of status is a UI projection displaying its value. You can even display controls in it:

CustomLayout {} & mUpdater->status.readProjected([&updater = mUpdater](const std::any& status) -> _<AView> {
   if (std::any_cast<AUpdater::StatusIdle>(&status)) {
       return _new<AButton>("Check for updates").connect(&AView::clicked, AUI_SLOT(updater)::checkForUpdates);
   }
   if (std::any_cast<AUpdater::StatusCheckingForUpdates>(&status)) {
       return Label { "Checking for updates..." };
   }
   if (auto downloading = std::any_cast<AUpdater::StatusDownloading>(&status)) {
       return Vertical {
           Label { "Downloading..." },
           _new<AProgressBar>() & downloading->progress,
       };
   }
   if (std::any_cast<AUpdater::StatusWaitingForApplyAndRestart>(&status)) {
       return _new<AButton>("Apply update and restart")
           .connect(&AView::clicked, AUI_SLOT(updater)::applyUpdateAndRestart);
   }
   return nullptr;
}),

© 2025 AUI Framework Contributors. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. All trademarks are property of their respective owners.

Contents

Debugging update deployment

View Page SourceEdit Page Source