Skip to content

Commit 62b5708

Browse files
Skycoder42Skycoder42
committed
add processbackend doc
1 parent 4746f00 commit 62b5708

File tree

4 files changed

+174
-8
lines changed

4 files changed

+174
-8
lines changed

‎doc/processbackend.dox‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
/*!
2+
@class QtAutoUpdater::ProcessBackend
3+
4+
When your custom updater plugin primarily uses some kind of commandline tool to check and install
5+
updates, using this class makes implementing such a plugin much easier than using UpdaterBackend
6+
directly. You should prefer this base class in such cases, unless there is a specific reason to not
7+
do so.
8+
9+
@sa QtAutoUpdater::UpdaterBackend, QProcess
10+
*/
11+
12+
/*!
13+
@fn QtAutoUpdater::ProcessBackend::readPathList
14+
15+
@param value The variant value to be parsed
16+
@returns A string list of paths extracted from the value
17+
18+
This method first checks the value. If it already is a QStringList, it is simply returned as one.
19+
If not, the value is converted to a QString and the split using QString::split with the given
20+
native path seperator (QDir::listSeparator) to create a string list from it.
21+
22+
Use this method over readStringList() when the list you are reading contains paths, as paths may
23+
contain spaces and other unexpected symbols. Using the native path seperator is the only safe way
24+
of splitting paths.
25+
26+
@sa UpdaterBackend::readStringList, ProcessBackend::readArgumentList, QDir::listSeparator,
27+
QString::split
28+
*/
29+
30+
/*!
31+
@fn QtAutoUpdater::ProcessBackend::readArgumentList
32+
33+
@param value The variant value to be parsed
34+
@returns A string list of arguments extracted from the value
35+
36+
This method first checks the value. If it already is a QStringList, it is simply returned as one.
37+
If not, the value is converted to a QString and then parsed. The parsing tries to seperate the string
38+
into quoted arguments, as they would be passed on a commandline. The arguments are split by spaces,
39+
but single and double quoted as well as backslash escaped characters are respected. For example, the
40+
following string would be seperated as shown below:
41+
42+
@code{.cpp}
43+
QString string = "hello world \"this is super\" and\\ very' use\"ful'"
44+
QStringList list = readArgumentList(string);
45+
// results in:
46+
{
47+
"hello",
48+
"world",
49+
"this is super",
50+
"and very use\"ful"
51+
}
52+
@endcode
53+
54+
@sa UpdaterBackend::readStringList, ProcessBackend::readPathList
55+
*/
56+
57+
/*!
58+
@fn QtAutoUpdater::ProcessBackend::runUpdateTool
59+
60+
@param id An internal identifier for the started process
61+
@param toolInfo The information about how to start the process
62+
63+
Call this method from checkForUpdates() to start a tool that performs the update check. The toolInfo
64+
struct holds all information about the process required to run it. The id is used to identify the
65+
process when it finished via onToolDone().
66+
67+
@note A process started this way will only emit onToolDone() if it executed without a crash. If it
68+
does crash, checkDone(false) is emitted automatically. If it does not crash, onToolDone() is called,
69+
even if the exit code is not 0. In that case, you are responsible for emitting that signal.
70+
71+
@sa ProcessBackend::UpdateProcessInfo, ProcessBackend::cancelUpdateTool, ProcessBackend::onToolDone,
72+
UpdaterBackend::checkDone
73+
*/
74+
75+
/*!
76+
@fn QtAutoUpdater::ProcessBackend::cancelUpdateTool
77+
78+
@param id The internal identifier of the process to be canceled
79+
@param kill Specify if the process should be terminated or killed
80+
81+
Call this method to stop a running process prematurely. If kill is true, QProcess::kill will be used
82+
to stop the process, QProcess::terminate otherwise. In both cases, the result handling stays the
83+
same. If the signal crashes the process, that is handled automatically. Otherwise onToolDone() is
84+
called.
85+
86+
@note The implementation of abort() of this class already does this automatically. Only use this
87+
method yourself, if you have to cancel a process for another reason.
88+
89+
@sa ProcessBackend::runUpdateTool, ProcessBackend::onToolDone
90+
*/
91+
92+
/*!
93+
@fn QtAutoUpdater::ProcessBackend::onToolDone
94+
95+
@param id The internal identifier of the finished process
96+
@param exitCode The code the process exited with
97+
@param processDevice The process as QIODevice to read data from it.
98+
99+
This method gets called by the library if a process that was started via runUpdateTool() finished
100+
without crashing. The id is same as passed to runUpdateTool(), the exit code is the one that the
101+
process returned. processDevice is set depending on the UpdateProcessInfo that was used to run the
102+
tool, as shown in the table below:
103+
104+
useStdout | useStderr | processDevice state
105+
------------|-----------|---------------------
106+
false | false | `nullptr`
107+
false | true | `QProcess*`, with stderr as active read channel
108+
true | false | `QProcess*`, with stdout as active read channel
109+
true | true | `QProcess*`, with stdout as active read channel
110+
111+
From withing this function, you should emit the checkDone() signals according to how you interpret
112+
the result exit code and output as soon as the last process you started finished.
113+
114+
@sa ProcessBackend::runUpdateTool, ProcessBackend::cancelUpdateTool,
115+
ProcessBackend::UpdateProcessInfo, UpdaterBackend::checkDone
116+
*/
117+
118+
/*!
119+
@fn QtAutoUpdater::ProcessBackend::installerInfo
120+
121+
@param infos A list of update infos to be updated
122+
@param track Specifies if the installers execution should be tracked
123+
@returns An optional install process information, if supported
124+
125+
This method is called from this classes triggerUpdates() implementation to get information about the
126+
process to be launched as external installer. If your backend does support launching an installer,
127+
return a valid information here. If it does not, return `nullopt` to communicate this to the
128+
library.
129+
130+
@note For this method to ever be called from the library, features() must have the
131+
UpdaterBackend::Feature::TriggerInstall flag set. Track can only be true if features() has the
132+
UpdaterBackend::Feature::ParallelTrigger flag set.
133+
134+
The launching, monitoring and handling of stdin/stderr/stdout is done automatically and
135+
triggerInstallDone() will also be emitted completely automatically if the process is tracked and
136+
did finish. After this method was called, you don't have to do anything regaring the triggered
137+
install anymore.
138+
139+
@sa UpdaterBackend::triggerUpdates, ProcessBackend::InstallProcessInfo, UpdaterBackend::features(),
140+
UpdaterBackend::Feature
141+
*/

‎doc/updaterbackend.dox‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ This method first checks the value. If it already is a QStringList, it is simply
125125
If not, the value is converted to a QString and the split using QString::split with the given
126126
seperator to create a string list from it.
127127

128-
@sa ProcessBackend::readPathList, ProcessBackend::readArgumentList
128+
@sa ProcessBackend::readPathList, ProcessBackend::readArgumentList, QString::split
129129
*/
130130

131131
/*!

‎src/autoupdatercore/processbackend.cpp‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,18 @@ void ProcessBackend::runUpdateTool(int id, ProcessBackend::UpdateProcessInfo too
106106
QIODevice::ReadOnly);
107107
}
108108

109+
void ProcessBackend::cancelUpdateTool(int id, bool kill)
110+
{
111+
Q_D(ProcessBackend);
112+
if (!d->updateProcesses.contains(id))
113+
return;
114+
115+
if (kill)
116+
d->updateProcesses[id].second->kill();
117+
else
118+
d->updateProcesses[id].second->terminate();
119+
}
120+
109121
QStringList ProcessBackend::readPathList(const QVariant &value)
110122
{
111123
return readStringList(value, QDir::listSeparator());

‎src/autoupdatercore/processbackend.h‎

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
namespace QtAutoUpdater {
1616

1717
class ProcessBackendPrivate;
18+
//! An extension of UpdaterBackend for easy implementation of QProcess based updater plugins
1819
class Q_AUTOUPDATERCORE_EXPORT ProcessBackend : public UpdaterBackend
1920
{
2021
Q_OBJECT
@@ -23,31 +24,43 @@ class Q_AUTOUPDATERCORE_EXPORT ProcessBackend : public UpdaterBackend
2324
void abort(bool force) override;
2425
bool triggerUpdates(const QList<QtAutoUpdater::UpdateInfo> &infos, bool track) override;
2526

27+
//! Helper function to convert a variant value into a string list of paths
2628
static QStringList readPathList(const QVariant &value);
29+
//! Helper function to convert a variant value into a string list of process arguments
2730
static QStringList readArgumentList(const QVariant &value);
2831

2932
protected:
33+
//! Structure that collects information about a process to be started
3034
struct Q_AUTOUPDATERCORE_EXPORT ProcessInfoBase {
31-
QString program;
32-
QStringList arguments;
33-
std::optional<QString> workingDir = std::nullopt;
35+
QString program; //!< The path or name of the executable
36+
QStringList arguments; //!< The arguments that should be passed to the process
37+
std::optional<QString> workingDir = std::nullopt; //!< The working directy. If set to nullopt, the programs path is used
3438
};
3539

40+
//! Structure that collects information about an update process to be started
3641
struct Q_AUTOUPDATERCORE_EXPORT UpdateProcessInfo : public ProcessInfoBase {
37-
bool useStdout = true;
38-
bool useStderr = false;
39-
std::optional<QByteArray> stdinData;
42+
bool useStdout = true; //!< Keep the stdout of the running process so it can be processed. Otherwise it is discarded
43+
bool useStderr = false; //!< Keep the stderr of the running process so it can be processed. Otherwise it is forwarded to the current processes stderr
44+
std::optional<QByteArray> stdinData; //!< Data to be passed to the stdin of the process once it started. Set this to nullopt to disable input
4045
};
4146

47+
//! Structure that collects information about an installation process to be started
4248
struct Q_AUTOUPDATERCORE_EXPORT InstallProcessInfo : public ProcessInfoBase {
43-
std::optional<bool> runAsAdmin = std::nullopt;
49+
std::optional<bool> runAsAdmin = std::nullopt; //!< Specify, if the process should be run as admin. If set to nullopt, the backend tries to figure this out by using AdminAuthoriser::needsAdminPermission(const QString &)
4450
};
4551

52+
//! Constructor using the backends key and a parent
4653
explicit ProcessBackend(QString &&key, QObject *parent = nullptr);
54+
//! @private
4755
explicit ProcessBackend(ProcessBackendPrivate &dd, QObject *parent = nullptr);
4856

57+
//! Starts the given updater tool for the id
4958
void runUpdateTool(int id, UpdateProcessInfo toolInfo);
59+
//! Send a termination request to the given process
60+
void cancelUpdateTool(int id, bool kill = false);
61+
//! Is called by the backend when the updater tool started for id has finished with a result
5062
virtual void onToolDone(int id, int exitCode, QIODevice *processDevice) = 0;
63+
//! Is called to get information about the tool to be run as external installer
5164
virtual std::optional<InstallProcessInfo> installerInfo(const QList<QtAutoUpdater::UpdateInfo> &infos, bool track) = 0;
5265

5366
private:

0 commit comments

Comments
 (0)