Updater class. More...

#include <AUI/Updater/AUpdater.h>

Classes#
struct	GetInstallationDirectoryContext
	Context for AUpdater::getInstallationDirectory. More...

struct	InstallCmdline
	Data required to launch installation child process. More...

struct	StatusCheckingForUpdates
	Checking for updates. More...

struct	StatusDownloading
	Downloading state. More...

struct	StatusIdle
	Idling. More...

struct	StatusNotAvailable
	AUpdater::isAvailable() evaluated to false. More...

struct	StatusWaitingForApplyAndRestart
	Waiting to applyUpdateAndRestart call state. More...

Public Member Functions#
virtual void	handlePostUpdateCleanup ()
	Performs post update cleanup routines.

virtual void	handleStartup (const AStringVector &applicationArguments)
	Performs a pre-application AUpdater routine.

virtual void	applyUpdateAndRestart ()
	Deploy the downloaded update.

void	checkForUpdates ()
	Sets `status` to StatusCheckingForUpdates and calls checkForUpdatesImpl, implemented by user.

void	downloadUpdate ()
	Sets `status` to StatusDownloading and calls downloadUpdateImpl, implemented by user.

const AOptional< AString > &	getLastDeploymentError () const noexcept

Public Member Functions inherited from AObject
_< AObject >	sharedPtr ()

_weak< AObject >	weakPtr ()

template<typename Connectable, ACompatibleSlotFor< Connectable > Function>
decltype(auto)	connect (const Connectable &connectable, Function &&function)
	Connects signal or property to slot of `"this"` object.

void	setSignalsEnabled (bool enabled)

bool	isSignalsEnabled () const noexcept

template<ASignalInvokable T>
void	operator^ (T &&t) noexcept

_< AAbstractThread >	getThread () const

bool	isSlotsCallsOnlyOnMyThread () const noexcept

void	setSlotsCallsOnlyOnMyThread (bool slotsCallsOnlyOnMyThread)

Public Member Functions inherited from AObjectBase
	AObjectBase (AObjectBase &&rhs) noexcept

	AObjectBase (const AObjectBase &rhs) noexcept

AObjectBase &	operator= (const AObjectBase &rhs) noexcept

AObjectBase &	operator= (AObjectBase &&rhs) noexcept

Public Member Functions inherited from aui::noncopyable
	noncopyable (const noncopyable &)=delete

noncopyable &	operator= (const noncopyable &)=delete

Static Public Member Functions#
static bool	isAvailable ()
	Checks that updater functionality is available.

Static Public Member Functions inherited from AObject
static void	disconnect ()

template<AAnySignal Signal, aui::derived_from< AObjectBase > Object, ACompatibleSlotFor< Signal > Function>
static decltype(auto)	connect (const Signal &signal, Object *object, Function &&function)
	Connects signal to the slot of the specified object.

template<AAnyProperty Property, aui::derived_from< AObjectBase > Object, typename Function>
static decltype(auto)	connect (const Property &property, Object *object, Function &&function)
	Connects property to the slot of the specified object.

template<APropertyReadable PropertySource, APropertyWritable PropertyDestination> requires requires { { propertySource } -> aui::convertible_to<std::decay_t<decltype(propertyDestination)>>; }
static void	connect (PropertySource &&propertySource, PropertyDestination &&propertyDestination)
	Connects source property to the destination property.

template<APropertyWritable PropertySource, APropertyWritable PropertyDestination> requires requires { { propertySource } -> aui::convertible_to<std::decay_t<decltype(propertyDestination)>>; { propertyDestination } -> aui::convertible_to<std::decay_t<decltype(propertySource)>>; }
static void	biConnect (PropertySource &&propertySource, PropertyDestination &&propertyDestination)
	Connects source property to the destination property and opposite (bidirectionally).

template<AAnySignalOrProperty Connectable, aui::derived_from< AObjectBase > Object, ACompatibleSlotFor< Connectable > Function>
static decltype(auto)	connect (const Connectable &connectable, Object &object, Function &&function)
	Connects signal or property to the slot of the specified object.

template<AAnySignalOrProperty Connectable, aui::derived_from< AObjectBase > Object, ACompatibleSlotFor< Connectable > Function>
static decltype(auto)	connect (const Connectable &connectable, _< Object > object, Function &&function)
	Connects signal or property to the slot of the specified object.

template<AAnySignalOrProperty Connectable, aui::derived_from< AObjectBase > Object, typename Function>
static decltype(auto)	connect (const Connectable &connectable, ASlotDef< Object *, Function > slotDef)
	Connects signal to the slot of the specified object. Slot is packed to single argument.

template<AAnyProperty Property, typename Object, ACompatibleSlotFor< Property > Function> requires (!aui::derived_from<Object, AObject>)
static void	connect (const Property &property, _< Object > object, Function &&function)
	Connects signal or property to the slot of the specified non-AObject type.

static void	moveToThread (aui::no_escape< AObject > object, _< AAbstractThread > thread)

Signals and public fields#
AProperty< std::any >	status
	State of the updater.

Protected Member Functions#
InstallCmdline	makeDefaultInstallationCmdline () const
	Constructs InstallCmdline with default arguments.

virtual void	triggerUpdateOnStartup ()
	Triggers update routine.

virtual AFuture< void >	downloadUpdateImpl (const APath &unpackedUpdateDir)=0
	Performs update delivery to the specified directory.

virtual AFuture< void >	checkForUpdatesImpl ()=0
	Check for updates user's implementation.

void	downloadAndUnpack (AString downloadUrl, const APath &unpackedUpdateDir)
	Typical download and unpack implementation.

void	reportDownloadedPercentage (aui::float_within_0_1 progress)
	Being called by downloadUpdateImpl, reports download percentage to `status`.

virtual AString	getModuleName () const
	Returns a module name of your (your_app_name or your_app_name.exe, without a leading path).

void	reportReadyToApplyAndRestart (InstallCmdline cmdline)
	Dumps InstallCmdline to temporary download directory, indicating that an update is ready to install. Updates status accordingly.

virtual APath	getTempWorkDir () const
	Working directory for AUpdater. By default, points to some path in TEMP.

virtual APath	getUnpackedUpdateDir () const
	The path where the update is unpacked to.

virtual AOptional< InstallCmdline >	loadInstallCmdline () const
	Restores install command line state, if any.

virtual void	saveCmdline (const InstallCmdline &cmdline) const
	Saves install command line to restore state when application is restarted.

virtual void	handleWaitForProcess (uint32_t pid)
	Handles –aui-updater-wait-for-process.

virtual AVector< AString >	injectWaitForMyPid (AVector< AString > args)
	Injects –aui-updater-wait-for-process=THIS_PROCESS_PID as the first argument.

virtual void	deployUpdate (const APath &source, const APath &destination)
	Deploys update by recursively copying (moving) files from source dir to destination dir.

virtual APath	getInstallationDirectory (const GetInstallationDirectoryContext &context)
	Retrieves installation directory based on given context.

virtual void	cleanupUnpackedUpdateDirBeforeDownloading ()
	called by AUpdater::downloadUpdate before downloading update to cleanup AUpdater::getUnpackedUpdateDir() dir.

Protected Member Functions inherited from AObject
void	setThread (_< AAbstractThread > thread)
	Set thread of the object.

Protected Member Functions inherited from AObjectBase
void	clearAllIngoingConnections () noexcept

virtual void	handleSlotException (std::exception_ptr exception)
	Called then an exception has thrown during slot processing of the signal emitted by this object.

Protected Attributes#
AAsyncHolder	mAsync
	Holder for async operations.

Additional Inherited Members#
Static Public Attributes inherited from AObject
static constexpr AObjectBase *	GENERIC_OBSERVER = nullptr
	Indicates that a connection should not be explicitly linked to receiver's lifetime.

Static Public Attributes inherited from AObjectBase
static ASpinlockMutex	SIGNAL_SLOT_GLOBAL_SYNC

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#

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

AUpdater::applyUpdateAndRestart

virtual void applyUpdateAndRestart()

Deploy the downloaded update.

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:

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, 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, slot(updater)::applyUpdateAndRestart);
    }
    return nullptr;
}),

Classes#

Public Member Functions#

Static Public Member Functions#

Signals and public fields#

Protected Member Functions#

Protected Attributes#

Additional Inherited Members#

Detailed Description#

Member Function Documentation#

◆ applyUpdateAndRestart()#

Debugging update deployment#

◆ checkForUpdates()#

◆ deployUpdate()#

◆ downloadAndUnpack()#

◆ downloadUpdate()#

◆ downloadUpdateImpl()#

◆ getInstallationDirectory()#

◆ getModuleName()#

◆ getUnpackedUpdateDir()#

◆ handlePostUpdateCleanup()#

◆ handleStartup()#

◆ isAvailable()#

◆ loadInstallCmdline()#

◆ makeDefaultInstallationCmdline()#

◆ reportDownloadedPercentage()#

◆ reportReadyToApplyAndRestart()#

◆ saveCmdline()#

◆ triggerUpdateOnStartup()#

Member Data Documentation#

◆ status#