An interface to be implemented by updater plugins to provide the updater functionalities. More...

#include <updaterbackend.h>

Inheritance diagram for QtAutoUpdater::UpdaterBackend:

Classes
class	IConfigReader
	A helper interface to allow backend generic access to a backends configuration. More...

Public Types
enum	Feature { Feature::CheckUpdates = 0x00, Feature::CheckProgress = 0x01, Feature::TriggerInstall = 0x02, Feature::ParallelTrigger = (TriggerInstall \| 0x04), Feature::PerformInstall = 0x08 }
	Various features a backend may or may not support. More...

using	SecondaryInfo = std::optional< std::pair< QString, QString > >
	Holds the variant map key and display name of the secondary update information.

Signals
void	checkProgress (double percent, const QString &status)
	Should be emitted when the check progress changes. More...

void	checkDone (bool success, const QList< QtAutoUpdater::UpdateInfo > &updates={})
	Should be emitted when the update check completed. More...

void	triggerInstallDone (bool success)
	Should be emitted when a tracked triggered installation finished. More...

Public Member Functions
Q_INVOKABLE QString	key () const
	Returns the key of this backend.

virtual Features	features () const =0
	Returns the supported features.

virtual SecondaryInfo	secondaryInfo () const
	Returns the secondary update info. More...

bool	initialize (QScopedPointer< IConfigReader > &&config)
	Initializes the backend with the given configuration.

virtual void	checkForUpdates ()=0
	Starts an update check. More...

virtual void	abort (bool force)=0
	Aborts an update check. More...

virtual bool	triggerUpdates (const QList< UpdateInfo > &infos, bool track)=0
	Launches an installer application to install updates. More...

virtual UpdateInstaller *	createInstaller ()=0
	Creates an update installer to internally install updates. More...

Public Member Functions inherited from QObject
virtual const QMetaObject *	metaObject () const const

	QObject (QObject *parent)

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

QString	objectName () const const

void	setObjectName (const QString &name)

bool	isWidgetType () const const

bool	isWindowType () const const

bool	signalsBlocked () const const

bool	blockSignals (bool block)

QThread *	thread () const const

void	moveToThread (QThread *targetThread)

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

void	killTimer (int id)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

const QObjectList &	children () const const

void	setParent (QObject *parent)

void	installEventFilter (QObject *filterObj)

void	removeEventFilter (QObject *obj)

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectTree ()

void	dumpObjectInfo ()

void	dumpObjectTree () const const

void	dumpObjectInfo () const const

bool	setProperty (const char *name, const QVariant &value)

QVariant	property (const char *name) const const

QList< QByteArray >	dynamicPropertyNames () const const

void	destroyed (QObject *obj)

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

bool	inherits (const char *className) const const

void	deleteLater ()

	Q_DISABLE_COPY (Class)

	Q_DISABLE_MOVE (Class)

	Q_DISABLE_COPY_MOVE (Class)

T	qobject_cast (QObject *object)

T	qobject_cast (const QObject *object)

T	qFindChild (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QRegExp &regExp)

	Q_CLASSINFO (Name, Value)

	Q_INTERFACES (...)

	Q_PROPERTY (...)

	Q_ENUMS (...)

	Q_FLAGS (...)

	Q_ENUM (...)

	Q_FLAG (...)

	Q_ENUM_NS (...)

	Q_FLAG_NS (...)

	Q_OBJECT Q_OBJECT

	Q_GADGET Q_GADGET

	Q_NAMESPACE Q_NAMESPACE

	Q_SIGNALS Q_SIGNALS

	Q_SIGNAL Q_SIGNAL

	Q_SLOTS Q_SLOTS

	Q_SLOT Q_SLOT

	Q_EMIT Q_EMIT

	Q_INVOKABLE Q_INVOKABLE

	Q_REVISION Q_REVISION

	Q_SET_OBJECT_NAME (Object)

	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT

Static Public Member Functions
static QStringList	readStringList (const QVariant &value, QChar listSeperator=QLatin1Char(','))
	Helper function to convert a variant value into a string list. More...

Static Public Member Functions inherited from QObject
QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

Protected Member Functions
	UpdaterBackend (QString &&key, QObject *parent=nullptr)
	Constructor using the backends key and a parent.

IConfigReader *	config () const
	Returns the configuration for this backend instance.

virtual bool	initialize ()=0
	Internally initializes the backend. More...

Protected Member Functions inherited from QObject
QObject *	sender () const const

int	senderSignalIndex () const const

int	receivers (const char *signal) const const

bool	isSignalConnected (const QMetaMethod &signal) const const

virtual void	timerEvent (QTimerEvent *event)

virtual void	childEvent (QChildEvent *event)

virtual void	customEvent (QEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

Additional Inherited Members
Public Attributes inherited from QObject
typedef	QObjectList

Properties inherited from QObject
	objectName

Detailed Description

An interface to be implemented by updater plugins to provide the updater functionalities.

This is the primary interface you need to implement when providing a custom updater backend. If you are only using the library with existing backends, you won't come in contact with this class.

Implement it following this documentation, and make sure to return the correct features(). Depending on the application, there might be multiple instances of one backend with different configurations. Be aware of this when implementing your own.

Note: If your custom backend is mostly focussed around running other executables for get update details etc., it is recommended to use ProcessBackend instead, as it simplifies this by a great amount.

See also: UpdaterPlugin, ProcessBackend, ProcessBackend::features, Updater Backend Plugins

Definition at line 22 of file updaterbackend.h.

Member Enumeration Documentation

◆ Feature

enum QtAutoUpdater::UpdaterBackend::Feature

strong

Various features a backend may or may not support.

Enumerator
CheckUpdates	The backend can check for updates. Must be supported by all backends.
CheckProgress	When checking for updates, the backend reports a detailed progress.
TriggerInstall	The backend can start an installation application if the primary application exits.
ParallelTrigger	The backend can start an installation application running parallel to the primary application.
PerformInstall	The backend can create an UpdateInstaller to perform an update internally.

Definition at line 28 of file updaterbackend.h.

Member Function Documentation

◆ abort()

QtAutoUpdater::UpdaterBackend::abort ( bool force )

pure virtual

Aborts an update check.

Parameters

force Specify, if the abortion should be forced or gentle

This method is called by the library to abort an ongoing update check. The force parameter specifies if the abort should be done gently or forced.

A gentle abort should stop the check if possible, but may take some time to gracefully do so. It is also possible for a soft abort to fail under certain conditions and simply continue with the check. A forced abort must be as fast as possible and should stop the check no matter what, even if that means that an invalid state might be reached.

Once canceled, the checkDone() must be emitted to notify the library. The success state of that signal should mirror how "clean" the abort was.

See also: UpdaterBackend::checkForUpdates, UpdaterBackend::checkDone

Implemented in QtAutoUpdater::ProcessBackend.

◆ checkDone

QtAutoUpdater::UpdaterBackend::checkDone	(	bool	success,
		const QList< QtAutoUpdater::UpdateInfo > &	updates = `{}`
	)

signal

Should be emitted when the update check completed.

Parameters

success	Reports whether the check was successfull or not
updates	Returns a list of updates, if some are available

Emit this signal to tell the library that checking for updates is done. Emit it with true if no error occured, even if no updates are available, as that is not considered an error. Simply leave updates empty in that case. If some are available, create UpdateInfos for them and pass them to updates.

Only set success to false, if an actual error occured (or when canceling unclean), as this will show a message to the user, that something went wrong.

See also: UpdaterBackend::checkForUpdates, UpdaterBackend::abort

◆ checkForUpdates()

QtAutoUpdater::UpdaterBackend::checkForUpdates ( )

pure virtual

Starts an update check.

This method is called by the library to start an update check. In here, you should do whatever is neccessary to perform the update check.

While the check is running, use checkProgress() to report the status and progress, and use checkDone() do report a result once done.

Attention: This method must be non blocking. It should only start the check for updates, not wait for it's completion. Exceptions are extremly shortrunning tasks, as e.g. checking a locally available file etc.

See also: UpdaterBackend::checkProgress, UpdaterBackend::checkDone, UpdaterBackend::abort

◆ checkProgress

QtAutoUpdater::UpdaterBackend::checkProgress	(	double	percent,
		const QString &	status
	)

signal

Should be emitted when the check progress changes.

Parameters

percent	A percentage value representing the check progress
status	A localized status string to explaing the current state of the check process

Emit this signal to give the user some feedback on the current state of the update check. percent can either range from 0.0 to 1.0 to present an actual percentage, or be -1.0 to represent an indeterminate progress. Status can be left empty to be unchanged/unset. Emitting this signal is optional, but recommended for long running checks.

Note: For this signal to be catched by the library, features() must have the UpdaterBackend::Feature::CheckProgress flag set.

See also: UpdaterBackend::checkForUpdates, UpdaterBackend::features(), UpdaterBackend::Feature

◆ createInstaller()

QtAutoUpdater::UpdaterBackend::createInstaller ( )

pure virtual

Creates an update installer to internally install updates.

Returns: An UpdateInstaller instance, if the backend supports it

Implement this method to return your implementation of a UpdateInstaller, if your backend supports a performed installation (See UpdateInstaller for more details on that). If your backend does not support this, simply return nullptr

Note: For this method to ever be called from the library, features() must have the UpdaterBackend::Feature::PerformInstall flag set.

See also: UpdateInstaller, UpdaterBackend::features(), UpdaterBackend::Feature, UpdaterBackend::triggerUpdates

◆ initialize()

QtAutoUpdater::UpdaterBackend::initialize ( )

protectedpure virtual

Internally initializes the backend.

Returns: true if initialization was successful, false if not

This method is internally called by initialize(QScopedPointer<IConfigReader> &&) to perform the actual initialization. This is done immediatly after the creation of the backend by the library. At this point, config() will return a valid object and can be used to configure the backend.

Return true if the init was successful and the backend can now be used normally. On a failure, return false and the backend will be deleted.

See also: UpdaterBackend::initialize(QScopedPointer<IConfigReader> &&), UpdaterBackend::config

◆ readStringList()

QtAutoUpdater::UpdaterBackend::readStringList	(	const QVariant &	value,
		QChar	listSeperator = `QLatin1Char(',')`
	)

static

Helper function to convert a variant value into a string list.

Parameters

value	The variant value to be parsed
listSeperator	The seperator to split a string by

Returns: A string list extracted from the value

This method first checks the value. If it already is a QStringList, it is simply returned as one. If not, the value is converted to a QString and the split using QString::split with the given seperator to create a string list from it.

See also: ProcessBackend::readPathList, ProcessBackend::readArgumentList, QString::split

◆ secondaryInfo()

QtAutoUpdater::UpdaterBackend::secondaryInfo ( ) const

virtual

Returns the secondary update info.

Returns: The secondary update information meta data

A UpdateInfo has the UpdateInfo::name and UpdateInfo::version property to show details to a user. However, the GUIs support a third column, with additional information stored in the UpdateInfo::data property, custom to each backend.

This method allows you to specify that additional data. The first of the pair should be the key to access the value within data, i.e. info.data()[info->first] should return the data to be displayed for each update info. second must hold a localized string to serve as header to that data.

If your backend does not have such information, simply return std::nullopt (or don't override this method)

See also: UpdateInfo

◆ triggerInstallDone

QtAutoUpdater::UpdaterBackend::triggerInstallDone ( bool success )

signal

Should be emitted when a tracked triggered installation finished.

Parameters

success Reports whether the installation was successfull or not

Emit this signal once an external installer, that was started with track set to true, finsihed it's execution. Use the parameter to report, whether the installer was successful or not. It is up to the developer of each backend to decide, whether updates not installed due to the user are considered an error or not.

Note: For this signal to be catched by the library, features() must have the UpdaterBackend::Feature::ParallelTrigger flag set, as only then triggerUpdates() can be called with track set to true.

See also: UpdaterBackend::triggerUpdates, UpdaterBackend::features(), UpdaterBackend::Feature

◆ triggerUpdates()

QtAutoUpdater::UpdaterBackend::triggerUpdates	(	const QList< UpdateInfo > &	infos,
		bool	track
	)

pure virtual

Launches an installer application to install updates.

Parameters

infos	A list of update infos to be updated
track	Specifies if the installers execution should be tracked

Returns: true if an installer was launched, false if not

This method should launch some kind of external installer application and report whether it could be launched successfully. The infos parameter can be seen as hint for what updates should be installed, but can be ignored if the external installer cannot be given that information.

Note: For this method to ever be called from the library, features() must have the UpdaterBackend::Feature::TriggerInstall flag set.

The track parameter specifies whether the execution of the external installer should be tracked. If true, than the backend should track the launched installer and emit triggerInstallDone() once the installer has completed the installation. If set to false, it should only be launched and then forgotten.

Note: track can only be true if features() has the UpdaterBackend::Feature::ParallelTrigger flag set. In that case, an installer might be run in parallel to the calling application. If that flag is not set, this method will only ever be called with track set to false and the calling application will exit immediatly after the installer was launched successfully. However, even if the feature is supported, it is still possible for track to be false and the application to exit.

See also: UpdaterBackend::features(), UpdaterBackend::Feature, UpdaterBackend::triggerInstallDone UpdaterBackend::createInstaller

Implemented in QtAutoUpdater::ProcessBackend.

The documentation for this class was generated from the following files:

updaterbackend.h
updaterbackend.dox

Classes

Public Types

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Feature

Member Function Documentation

◆ abort()

◆ checkDone

◆ checkForUpdates()

◆ checkProgress

◆ createInstaller()

◆ initialize()

◆ readStringList()

◆ secondaryInfo()

◆ triggerInstallDone

◆ triggerUpdates()