An extension of UpdaterBackend for easy implementation of QProcess based updater plugins. More...

#include <processbackend.h>

Inheritance diagram for QtAutoUpdater::ProcessBackend:

Classes
struct	InstallProcessInfo
	Structure that collects information about an installation process to be started. More...

struct	ProcessInfoBase
	Structure that collects information about a process to be started. More...

struct	UpdateProcessInfo
	Structure that collects information about an update process to be started. More...

Public Member Functions
void	abort (bool force) override
	Aborts an update check. More...

bool	triggerUpdates (const QList< QtAutoUpdater::UpdateInfo > &infos, bool track) override
	Launches an installer application to install updates. More...

Public Member Functions inherited from QtAutoUpdater::UpdaterBackend
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 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	readPathList (const QVariant &value)
	Helper function to convert a variant value into a string list of paths. More...

static QStringList	readArgumentList (const QVariant &value)
	Helper function to convert a variant value into a string list of process arguments. More...

Static Public Member Functions inherited from QtAutoUpdater::UpdaterBackend
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
	ProcessBackend (QString &&key, QObject *parent=nullptr)
	Constructor using the backends key and a parent.

void	runUpdateTool (int id, UpdateProcessInfo toolInfo)
	Starts the given updater tool for the id. More...

void	cancelUpdateTool (int id, bool kill=false)
	Send a termination request to the given process. More...

virtual void	onToolDone (int id, int exitCode, QIODevice *processDevice)=0
	Is called by the backend when the updater tool started for id has finished with a result. More...

virtual std::optional< InstallProcessInfo >	installerInfo (const QList< QtAutoUpdater::UpdateInfo > &infos, bool track)=0
	Is called to get information about the tool to be run as external installer. More...

Protected Member Functions inherited from QtAutoUpdater::UpdaterBackend
	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 Types inherited from QtAutoUpdater::UpdaterBackend
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 inherited from QtAutoUpdater::UpdaterBackend
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 Attributes inherited from QObject
typedef	QObjectList

Properties inherited from QObject
	objectName

Detailed Description

An extension of UpdaterBackend for easy implementation of QProcess based updater plugins.

When your custom updater plugin primarily uses some kind of commandline tool to check and install updates, using this class makes implementing such a plugin much easier than using UpdaterBackend directly. You should prefer this base class in such cases, unless there is a specific reason to not do so.

See also: QtAutoUpdater::UpdaterBackend, QProcess

Definition at line 19 of file processbackend.h.

Member Function Documentation

◆ abort()

void QtAutoUpdater::ProcessBackend::abort ( bool force )

overridevirtual

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

Implements QtAutoUpdater::UpdaterBackend.

◆ cancelUpdateTool()

QtAutoUpdater::ProcessBackend::cancelUpdateTool	(	int	id,
		bool	kill = `false`
	)

protected

Send a termination request to the given process.

Parameters

id	The internal identifier of the process to be canceled
kill	Specify if the process should be terminated or killed

Call this method to stop a running process prematurely. If kill is true, QProcess::kill will be used to stop the process, QProcess::terminate otherwise. In both cases, the result handling stays the same. If the signal crashes the process, that is handled automatically. Otherwise onToolDone() is called.

Note: The implementation of abort() of this class already does this automatically. Only use this method yourself, if you have to cancel a process for another reason.

See also: ProcessBackend::runUpdateTool, ProcessBackend::onToolDone

◆ installerInfo()

QtAutoUpdater::ProcessBackend::installerInfo	(	const QList< QtAutoUpdater::UpdateInfo > &	infos,
		bool	track
	)

protectedpure virtual

Is called to get information about the tool to be run as external installer.

Parameters

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

Returns: An optional install process information, if supported

This method is called from this classes triggerUpdates() implementation to get information about the process to be launched as external installer. If your backend does support launching an installer, return a valid information here. If it does not, return nullopt to communicate this to the library.

Note: For this method to ever be called from the library, features() must have the UpdaterBackend::Feature::TriggerInstall flag set. Track can only be true if features() has the UpdaterBackend::Feature::ParallelTrigger flag set.

The launching, monitoring and handling of stdin/stderr/stdout is done automatically and triggerInstallDone() will also be emitted completely automatically if the process is tracked and did finish. After this method was called, you don't have to do anything regaring the triggered install anymore.

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

◆ onToolDone()

QtAutoUpdater::ProcessBackend::onToolDone	(	int	id,
		int	exitCode,
		QIODevice *	processDevice
	)

protectedpure virtual

Is called by the backend when the updater tool started for id has finished with a result.

Parameters

id	The internal identifier of the finished process
exitCode	The code the process exited with
processDevice	The process as QIODevice to read data from it.

This method gets called by the library if a process that was started via runUpdateTool() finished without crashing. The id is same as passed to runUpdateTool(), the exit code is the one that the process returned. processDevice is set depending on the UpdateProcessInfo that was used to run the tool, as shown in the table below:

useStdout	useStderr	processDevice state
false	false	`nullptr`
false	true	`QProcess*`, with stderr as active read channel
true	false	`QProcess*`, with stdout as active read channel
true	true	`QProcess*`, with stdout as active read channel

From withing this function, you should emit the checkDone() signals according to how you interpret the result exit code and output as soon as the last process you started finished.

See also: ProcessBackend::runUpdateTool, ProcessBackend::cancelUpdateTool, ProcessBackend::UpdateProcessInfo, UpdaterBackend::checkDone

◆ readArgumentList()

QtAutoUpdater::ProcessBackend::readArgumentList ( const QVariant & value )

static

Helper function to convert a variant value into a string list of process arguments.

Parameters

value The variant value to be parsed

Returns: A string list of arguments 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 then parsed. The parsing tries to seperate the string into quoted arguments, as they would be passed on a commandline. The arguments are split by spaces, but single and double quoted as well as backslash escaped characters are respected. For example, the following string would be seperated as shown below:

QString string = "hello world \"this is super\" and\\ very' use\"ful'"
QStringList list = readArgumentList(string);
// results in:
{
    "hello",
    "world",
    "this is super",
    "and very use\"ful"
}

See also: UpdaterBackend::readStringList, ProcessBackend::readPathList

◆ readPathList()

QtAutoUpdater::ProcessBackend::readPathList ( const QVariant & value )

static

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

Parameters

value The variant value to be parsed

Returns: A string list of paths 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 native path seperator (QDir::listSeparator) to create a string list from it.

Use this method over readStringList() when the list you are reading contains paths, as paths may contain spaces and other unexpected symbols. Using the native path seperator is the only safe way of splitting paths.

See also: UpdaterBackend::readStringList, ProcessBackend::readArgumentList, QDir::listSeparator, QString::split

◆ runUpdateTool()

QtAutoUpdater::ProcessBackend::runUpdateTool	(	int	id,
		UpdateProcessInfo	toolInfo
	)

protected

Starts the given updater tool for the id.

Parameters

id	An internal identifier for the started process
toolInfo	The information about how to start the process

Call this method from checkForUpdates() to start a tool that performs the update check. The toolInfo struct holds all information about the process required to run it. The id is used to identify the process when it finished via onToolDone().

Note: A process started this way will only emit onToolDone() if it executed without a crash. If it does crash, checkDone(false) is emitted automatically. If it does not crash, onToolDone() is called, even if the exit code is not 0. In that case, you are responsible for emitting that signal.

See also: ProcessBackend::UpdateProcessInfo, ProcessBackend::cancelUpdateTool, ProcessBackend::onToolDone, UpdaterBackend::checkDone

◆ triggerUpdates()

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

overridevirtual

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.