Skip to content

Commit 4746f00

Browse files
Skycoder42Skycoder42
committed
wip doc
1 parent 2535cfe commit 4746f00

File tree

12 files changed

+557
-107
lines changed

12 files changed

+557
-107
lines changed

‎doc/Doxyfile‎

Lines changed: 145 additions & 80 deletions
Large diffs are not rendered by default.

‎doc/adminauthoriser.dox‎

Lines changed: 30 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,47 @@
11
/*!
2-
@class QtAutoUpdater::AdminAuthoriser
2+
@namespace QtAutoUpdater::AdminAuthoriser
33

4-
The AdminAuthoriser's task is to run a program with elevated rigths. Since the way to archive this is different
5-
on every platform, the authoriser is an interface. Because the "default" way to gain elevated privilegs is doing so
6-
by using a GUI, the default implementation is done in the AutoUpdaterWidgets library. If you intend to use the
7-
core library only, you will have to implement admin-authorisation yourself (if you require it)
4+
@brief Methods to run applications as authorized user (admin/root)
85

9-
@sa Updater::runUpdaterOnExit(AdminAuthoriser *)
6+
The AdminAuthoriser's task is to run a program with elevated rigths. Since the way to archive this is
7+
different on every platform, it will behave differently on different systems. Generelly it will prompt
8+
the user for admin credentials using the system API and then execute the program on success. This may
9+
not work on any platform.
10+
11+
This namespace can be used when implementing custom plugins to run elevated tasks
1012
*/
1113

1214
/*!
13-
@fn QtAutoUpdater::AdminAuthoriser::hasAdminRights
15+
@fn QtAutoUpdater::AdminAuthoriser::needsAdminPermission(const QString &)
16+
17+
@returns `true`, if this program needs to be run as priviledged user, `false` if not or unable to determine
18+
19+
This might return false even if a application needs such permissions in three cases:
1420

15-
@returns `true`, if this program does have elevated rights, `false` if not
21+
1. The system is unable to figure out, whether the program needs that permission
22+
2. The current application is already running with elevated rights
23+
3. The check is not supported on the current platform
1624

17-
If `true` is returned, the updater assumes that by starting a normal QProcess the launched process will inherit
18-
this elevation and will be elevated too. If thats not the case, return `false`. The updater will call AdminAuthoriser::executeAsAdmin
19-
instead.
25+
@sa AdminAuthoriser::executeAsAdmin
2026
*/
2127

2228
/*!
23-
@fn QtAutoUpdater::AdminAuthoriser::executeAsAdmin
29+
@fn QtAutoUpdater::AdminAuthoriser::executeAsAdmin(const QString &, const QStringList &, const QString &)
2430

2531
@param program The path to the executable. This will be an absolute path
26-
@param arguments A list of arguments to be passed to the executable. Can be empty
32+
@param arguments A list of arguments to be passed to the executable
33+
@param workingDir The working directory to execute the program in. Should always be a valid path
2734
@returns `true`, if the program could be started with **elevated rights**, `false` if not
2835

29-
The actual elevation and execution should be done using this function. Please note that it's possible that this function
30-
is called while the QCoreApplication is shutting down. If `false` is returned, no error will be shown to the user. If you want
31-
to do so, do it inside that function.
36+
This function will try to prompt the user for elevation and the execute the given program with
37+
elevation. Please note that workingDir may be ignored on some platforms. You should not rely on it
38+
beeing set correctly. Also, it may return `true`, even if the user rejected priviledged execution.
39+
40+
This function can return false if:
41+
42+
1. The user rejected the priviledged execution (but this may result in a successful return as well)
43+
2. The user accepted, but the operating system was not able to start the process
44+
3. The execution is not supported on the current platform
3245

33-
@note `program` will return an absolute path using normal slashes `/`, even on windows. If you need to use native APIs,
34-
get the correct path using QDir::toNativeSeparators.
46+
@sa AdminAuthoriser::needsAdminPermission
3547
*/

‎doc/autoupdater.dox‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,17 @@ independet of the Widgets-Library and won't need a gui. The Widgets-Library requ
99
a gui and the Core-Library.
1010

1111
## Core-Library:
12-
- Updater
13-
- AdminAuthoriser
12+
- Updater
13+
- UpdateInfo
14+
- UpdateInstaller
15+
- UpdaterPlugin
16+
- UpdaterBackend
17+
- ProcessBackend
18+
- AdminAuthoriser
1419

1520
## Widgets-Libray:
16-
- UpdateController
17-
- UpdateButton
21+
- UpdateController
22+
- UpdateButton
1823
*/
1924

2025
/*!

‎doc/updateinfo.dox‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
/*!
2+
@class QtAutoUpdater::UpdateInfo
3+
4+
A data gadget that holds details about updates. It is used to present updates information. While
5+
id, name and version are common to all backends, any additional information, like size, old versions,
6+
etc. are different for each backend and stored within the data property.
7+
8+
@sa @ref backends_TODO "Updater Backend Plugins"
9+
*/
10+
11+
/*!
12+
@property QtAutoUpdater::UpdateInfo::identifier
13+
14+
@default{`<invalid>`}
15+
16+
This id is different for each backend regarding both it's type and value. The only assumption you can
17+
make about this id is, that it is comparable. You should never actually read the data of the returned
18+
QVariant. Only use it index in a map or similar, to identify update information.
19+
20+
@accessors{
21+
@readAc{identifier()}
22+
@writeAc{setIdentifier()}
23+
}
24+
25+
@sa UpdateInfo::name
26+
*/
27+
28+
/*!
29+
@property QtAutoUpdater::UpdateInfo::name
30+
31+
@default{`<empty>`}
32+
33+
This should be a human readable name as returned by the backends. There are no assumptions you can
34+
make regarding the format, language, etc. of this name. It is unique to each backend and follows the
35+
package conventions of that backend.
36+
37+
@accessors{
38+
@readAc{name()}
39+
@writeAc{setName()}
40+
}
41+
42+
@sa UpdateInfo::identifier
43+
*/
44+
45+
/*!
46+
@property QtAutoUpdater::UpdateInfo::version
47+
48+
@default{`<empty version>`}
49+
50+
The version can be used to compare versions of components or to be displayed to the user. It may not
51+
be the full version string of the underlying backend, as QVersionNumber strips versions down to
52+
segments only.
53+
54+
@accessors{
55+
@readAc{version()}
56+
@writeAc{setVersion()}
57+
}
58+
59+
@sa UpdateInfo::data
60+
*/
61+
62+
/*!
63+
@property QtAutoUpdater::UpdateInfo::data
64+
65+
@default{`<empty map>`}
66+
67+
What this map contains depends fully on the backend and any additional information it may provide.
68+
Check the @ref backends_TODO "Updater Backend Plugins" documentation for more details.
69+
70+
@accessors{
71+
@readAc{data()}
72+
@writeAc{setData()}
73+
}
74+
75+
@sa UpdateInfo::version, @ref backends_TODO "Updater Backend Plugins"
76+
*/

‎doc/updaterbackend.dox‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
/*!
2+
@class QtAutoUpdater::UpdaterBackend
3+
4+
This is the primary interface you need to implement when providing a custom updater backend. If you
5+
are only using the library with existing backends, you won't come in contact with this class.
6+
7+
Implement it following this documentation, and make sure to return the correct features(). Depending
8+
on the application, there might be multiple instances of one backend with different configurations.
9+
Be aware of this when implementing your own.
10+
11+
@note If your custom backend is mostly focussed around running other executables for get update
12+
details etc., it is recommended to use ProcessBackend instead, as it simplifies this by a great
13+
amount.
14+
15+
@sa UpdaterPlugin, ProcessBackend, ProcessBackend::features
16+
*/
17+
18+
/*!
19+
@fn QtAutoUpdater::UpdaterBackend::secondaryInfo
20+
21+
@returns The secondary update information meta data
22+
23+
A UpdateInfo has the UpdateInfo::name and UpdateInfo::version property to show details to a user.
24+
However, the GUIs support a third column, with additional information stored in the UpdateInfo::data
25+
property, custom to each backend.
26+
27+
This method allows you to specify that additional data. The `first` of the pair should be the key to
28+
access the value within data, i.e. `info.data()[info->first]` should return the data to be displayed
29+
for each update info. `second` must hold a localized string to serve as header to that data.
30+
31+
If your backend does not have such information, simply return `std::nullopt` (or don't override this
32+
method)
33+
34+
@sa UpdateInfo
35+
*/
36+
37+
/*!
38+
@fn QtAutoUpdater::UpdaterBackend::checkForUpdates
39+
40+
This method is called by the library to start an update check. In here, you should do whatever is
41+
neccessary to perform the update check.
42+
43+
While the check is running, use checkProgress() to report the status and progress, and use
44+
checkDone() do report a result once done.
45+
46+
@attention This method must be non blocking. It should only start the check for updates, not wait for
47+
it's completion. Exceptions are extremly shortrunning tasks, as e.g. checking a locally available
48+
file etc.
49+
50+
@sa UpdaterBackend::checkProgress, UpdaterBackend::checkDone, UpdaterBackend::abort
51+
*/
52+
53+
/*!
54+
@fn QtAutoUpdater::UpdaterBackend::abort
55+
56+
@param force Specify, if the abortion should be forced or gentle
57+
58+
This method is called by the library to abort an ongoing update check. The force parameter specifies
59+
if the abort should be done gently or forced.
60+
61+
A gentle abort should stop the check if possible, but may take some time to gracefully do so. It is
62+
also possible for a soft abort to fail under certain conditions and simply continue with the check.
63+
A forced abort must be as fast as possible and should stop the check no matter what, even if that
64+
means that an invalid state might be reached.
65+
66+
Once canceled, the checkDone() must be emitted to notify the library. The success state of that
67+
signal should mirror how "clean" the abort was.
68+
69+
@sa UpdaterBackend::checkForUpdates, UpdaterBackend::checkDone
70+
*/
71+
72+
/*!
73+
@fn QtAutoUpdater::UpdaterBackend::triggerUpdates
74+
75+
@param infos A list of update infos to be updated
76+
@param track Specifies if the installers execution should be tracked
77+
@returns `true` if an installer was launched, `false` if not
78+
79+
This method should launch some kind of external installer application and report whether it could be
80+
launched successfully. The infos parameter can be seen as hint for what updates should be installed,
81+
but can be ignored if the external installer cannot be given that information.
82+
83+
@note For this method to ever be called from the library, features() must have the
84+
UpdaterBackend::Feature::TriggerInstall flag set.
85+
86+
The track parameter specifies whether the execution of the external installer should be tracked. If
87+
true, than the backend should track the launched installer and emit triggerInstallDone() once the
88+
installer has completed the installation. If set to false, it should only be launched and then
89+
forgotten.
90+
91+
@note track can only be true if features() has the UpdaterBackend::Feature::ParallelTrigger flag set.
92+
In that case, an installer might be run in parallel to the calling application. If that flag is not
93+
set, this method will only ever be called with track set to false and the calling application will
94+
exit immediatly after the installer was launched successfully. However, even if the feature is
95+
supported, it is still possible for track to be false and the application to exit.
96+
97+
@sa UpdaterBackend::features(), UpdaterBackend::Feature, UpdaterBackend::triggerInstallDone
98+
UpdaterBackend::createInstaller
99+
*/
100+
101+
/*!
102+
@fn QtAutoUpdater::UpdaterBackend::createInstaller
103+
104+
@returns An UpdateInstaller instance, if the backend supports it
105+
106+
Implement this method to return your implementation of a UpdateInstaller, if your backend supports
107+
a performed installation (See UpdateInstaller for more details on that). If your backend does not
108+
support this, simply return `nullptr`
109+
110+
@note For this method to ever be called from the library, features() must have the
111+
UpdaterBackend::Feature::PerformInstall flag set.
112+
113+
@sa UpdateInstaller, UpdaterBackend::features(), UpdaterBackend::Feature,
114+
UpdaterBackend::triggerUpdates
115+
*/
116+
117+
/*!
118+
@fn QtAutoUpdater::UpdaterBackend::readStringList
119+
120+
@param value The variant value to be parsed
121+
@param listSeperator The seperator to split a string by
122+
@returns A string list extracted from the value
123+
124+
This method first checks the value. If it already is a QStringList, it is simply returned as one.
125+
If not, the value is converted to a QString and the split using QString::split with the given
126+
seperator to create a string list from it.
127+
128+
@sa ProcessBackend::readPathList, ProcessBackend::readArgumentList
129+
*/
130+
131+
/*!
132+
@fn QtAutoUpdater::UpdaterBackend::checkProgress
133+
134+
@param percent A percentage value representing the check progress
135+
@param status A localized status string to explaing the current state of the check process
136+
137+
Emit this signal to give the user some feedback on the current state of the update check. percent can
138+
either range from 0.0 to 1.0 to present an actual percentage, or be -1.0 to represent an
139+
indeterminate progress. Status can be left empty to be unchanged/unset. Emitting this signal is
140+
optional, but recommended for long running checks.
141+
142+
@note For this signal to be catched by the library, features() must have the
143+
UpdaterBackend::Feature::CheckProgress flag set.
144+
145+
@sa UpdaterBackend::checkForUpdates, UpdaterBackend::features(), UpdaterBackend::Feature
146+
*/
147+
148+
/*!
149+
@fn QtAutoUpdater::UpdaterBackend::checkDone
150+
151+
@param success Reports whether the check was successfull or not
152+
@param updates Returns a list of updates, if some are available
153+
154+
Emit this signal to tell the library that checking for updates is done. Emit it with `true` if no
155+
error occured, even if no updates are available, as that is not considered an error. Simply leave
156+
updates empty in that case. If some are available, create UpdateInfos for them and pass them to
157+
updates.
158+
159+
Only set success to `false`, if an actual error occured (or when canceling unclean), as this will
160+
show a message to the user, that something went wrong.
161+
162+
@sa UpdaterBackend::checkForUpdates, UpdaterBackend::abort
163+
*/
164+
165+
/*!
166+
@fn QtAutoUpdater::UpdaterBackend::triggerInstallDone
167+
168+
@param success Reports whether the installation was successfull or not
169+
170+
Emit this signal once an external installer, that was started with track set to true, finsihed it's
171+
execution. Use the parameter to report, whether the installer was successful or not. It is up to the
172+
developer of each backend to decide, whether updates not installed due to the user are considered an
173+
error or not.
174+
175+
@note For this signal to be catched by the library, features() must have the
176+
UpdaterBackend::Feature::ParallelTrigger flag set, as only then triggerUpdates() can be called with
177+
track set to true.
178+
179+
@sa UpdaterBackend::triggerUpdates, UpdaterBackend::features(), UpdaterBackend::Feature
180+
*/
181+
182+
/*!
183+
@fn QtAutoUpdater::UpdaterBackend::initialize()
184+
185+
@returns `true` if initialization was successful, `false` if not
186+
187+
This method is internally called by initialize(QScopedPointer<IConfigReader> &&) to perform the
188+
actual initialization. This is done immediatly after the creation of the backend by the library. At
189+
this point, config() will return a valid object and can be used to configure the backend.
190+
191+
Return true if the init was successful and the backend can now be used normally. On a failure, return
192+
false and the backend will be deleted.
193+
194+
@sa UpdaterBackend::initialize(QScopedPointer<IConfigReader> &&), UpdaterBackend::config
195+
*/

0 commit comments

Comments
 (0)