From 5ee5386b3e460c8b9681feda46a5031810a0527e Mon Sep 17 00:00:00 2001 From: antony-jr Date: Tue, 30 Mar 2021 22:06:05 +0530 Subject: [PATCH] =?UTF-8?q?=F0=9F=A5=B3Release=20v2.0.1=20=F0=9F=A5=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/test-and-deploy.yml | 9 +- src/qappimageupdate_p.cc | 2 + tests/CMakeLists.txt | 5 + tests/QAppImageUpdateTests.hpp | 2 + website/i18n/en.json | 8 + website/package.json | 2 +- .../version-2.0.1/ClassQAppImageUpdate.md | 424 ++++++++++++++++++ .../version-2.0.1/PluginInterface.md | 379 ++++++++++++++++ website/versions.json | 1 + 9 files changed, 830 insertions(+), 2 deletions(-) create mode 100644 website/versioned_docs/version-2.0.1/ClassQAppImageUpdate.md create mode 100644 website/versioned_docs/version-2.0.1/PluginInterface.md diff --git a/.github/workflows/test-and-deploy.yml b/.github/workflows/test-and-deploy.yml index a23a68d..643f586 100644 --- a/.github/workflows/test-and-deploy.yml +++ b/.github/workflows/test-and-deploy.yml @@ -55,10 +55,17 @@ jobs: run: | Xvfb :100 -ac & export DISPLAY=:100.0 + source /opt/qt*/bin/qt*-env.sh || true cd .. + mkdir test-build + cd test-build + cmake -DBUILD_TESTS=ON .. + make -j$(nproc) + ./tests/QAppImageUpdateTests + cd .. + rm -rf test-build mkdir build cd build - source /opt/qt*/bin/qt*-env.sh || true cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=On -DDECENTRALIZED_UPDATE_ENABLED=ON -DBUILD_TESTS=ON .. make -j$(nproc) cd tests diff --git a/src/qappimageupdate_p.cc b/src/qappimageupdate_p.cc index f53568a..bb37275 100644 --- a/src/qappimageupdate_p.cc +++ b/src/qappimageupdate_p.cc @@ -640,6 +640,7 @@ void QAppImageUpdatePrivate::handleCheckForUpdateError(short code) { emit error(code, n_CurrentAction); } +#ifdef DECENTRALIZED_UPDATE_ENABLED void QAppImageUpdatePrivate::handleSeedError(short code) { b_Canceled = b_Started = b_Running = false; b_Finished = false; @@ -688,6 +689,7 @@ void QAppImageUpdatePrivate::handleSeedCancel() { QJsonObject r { }; emit finished(r, n_CurrentAction); } +#endif // DECENTRALIZED_UPDATE_ENABLED void QAppImageUpdatePrivate::redirectUpdateCheck(QJsonObject info) { disconnect(m_UpdateInformation.data(), SIGNAL(info(QJsonObject)), diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index befeadc..0fb4be2 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -24,5 +24,10 @@ if(QUICK_TEST) add_definitions(-DQUICK_TEST) endif() +if(DECENTRALIZED_UPDATE_ENABLED) + message("-- [*] IMPORTANT: Decentralized update feature will be TESTED.") + add_definitions(-DDECENTRALIZED_UPDATE_ENABLED) +endif() + add_executable(QAppImageUpdateTests main.cc QAppImageUpdateTests.hpp SimpleDownload.hpp) target_link_libraries(QAppImageUpdateTests PRIVATE QAppImageUpdate Qt5::Test Qt5::Concurrent) diff --git a/tests/QAppImageUpdateTests.hpp b/tests/QAppImageUpdateTests.hpp index 9d0c287..65709c0 100644 --- a/tests/QAppImageUpdateTests.hpp +++ b/tests/QAppImageUpdateTests.hpp @@ -456,6 +456,7 @@ class QAppImageUpdateTests : public QObject { QVERIFY(action == QAppImageUpdate::Action::Update); } +#ifdef DECENTRALIZED_UPDATE_ENABLED void actionUpdateWithTorrent() { short action = 0; QJsonObject result; @@ -509,6 +510,7 @@ class QAppImageUpdateTests : public QObject { } } } +#endif // DECENTRALIZED_UPDATE_ENABLED //// This should not crash the test //// That is the test. diff --git a/website/i18n/en.json b/website/i18n/en.json index 7677118..2a4064f 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -148,6 +148,14 @@ "version-2.0.0/version-2.0.0-UsingPlugin": { "title": "Build QAppImageUpdate as Qt Plugin", "sidebar_label": "Building as Qt Plugin" + }, + "version-2.0.1/version-2.0.1-ClassQAppImageUpdate": { + "title": "Class QAppImageUpdate", + "sidebar_label": "Class QAppImageUpdate" + }, + "version-2.0.1/version-2.0.1-PluginInterface": { + "title": "QAppImageUpdate Plugin Interface", + "sidebar_label": "Qt Plugin Interface" } }, "links": { diff --git a/website/package.json b/website/package.json index 0ea4623..68f0c85 100644 --- a/website/package.json +++ b/website/package.json @@ -11,5 +11,5 @@ "devDependencies": { "docusaurus": "^1.14.4" }, - "version": "0.0.0" + "version": "2.0.1" } diff --git a/website/versioned_docs/version-2.0.1/ClassQAppImageUpdate.md b/website/versioned_docs/version-2.0.1/ClassQAppImageUpdate.md new file mode 100644 index 0000000..139b3e7 --- /dev/null +++ b/website/versioned_docs/version-2.0.1/ClassQAppImageUpdate.md @@ -0,0 +1,424 @@ +--- +id: version-2.0.1-ClassQAppImageUpdate +title: Class QAppImageUpdate +sidebar_label: Class QAppImageUpdate +original_id: ClassQAppImageUpdate +--- + +| | | +|-----------|----------------------------------------------------------| +| Header: | #include < QAppImageUpdate > | +| qmake: | include(QAppImageUpdate/QAppImageUpdate.pri) | +|Inherits: | [QObject](http://doc.qt.io/qt-5/qobject.html) | + + +QAppImageUpdate is the main class which *Reads Embeded Update Information*, *Checks for Updates*, *Writes the Delta*, +*Downloads The Remaining Blocks* and finally *Verifies the Checksums.* + +In each stage, You can connect with specific signals to listen to each stage of the revision process(You can also control them). +Thus all you need is this class to do the entire update. + +Internally this class purely uses **signals and slots** to communicate to private classes which are single thread and non-blocking(Optionally runs in a separate thread). This class only holds a pointer to the private implementation (*PIMPL*). +For most of the time, This class does not leak memory but if it does please report it on github. + +All methods in this class is [reentrant](https://doc.qt.io/qt-5/threads-reentrancy.html) and thread safe. + +## Public Functions + +| Return Type | Name | +|--------------|------------------------------------------------------------------------------------------------| +| | [QAppImageUpdate(bool singleThreaded = true, QObject \*parent = nullptr)](#qappimageupdatebool-singlethreaded--true-qobject-parent--nullptr) | +| | [QAppImageUpdate(const QString&, bool singleThreaded = true, QObject \*parent = nullptr)](#qappimageupdateconst-qstring-bool-singlethreaded--true-qobject-parent--nullptr) | +| | [QAppImageUpdate(QFile \*, bool singleThreaded = true, QObject \*parent = nullptr)](#qappimageupdateqfile--bool-singlethreaded--true-qobject-parent--nullptr) | + + +## Slots + +| Return Type | Name | +|------------------------------|-------------------------------------------| +| **void** | [setGuiFlag(int)](#void-setguiflagint-flag) | +| **void** | [setIcon(QByteArray)](#void-seticonqbytearray-icon) | +| **void** | [start(short)](#void-startshort-action) | +| **void** | [cancel()](#void-cancel) | +| **void** | [setApplicationName(const QString&)](#void-setapplicationname-qstring) | +| **void** | [setAppImage(const QString&)](#void-setappimageconst-qstring) | +| **void** | [setAppImage(QFile \*)](#void-setappimageqfile-) | +| **void** | [setShowLog(bool)](#void-setshowlogbool) | +| **void** | [setOutputDirectory(const QString&)](#void-setoutputdirectoryconst-qstring) | +| **void** | [setProxy(const QNetworkProxy&)](#void-setproxyconst-qnetworkproxyhttpsdocqtioqt-5qnetworkproxyhtml) | +| **void** | [clear()](#void-clear) | + +## Signals + +| Return Type | Name | +|--------------|------------------------------------------------| +| void | [torrentClientStarted()](#void-torrentclientstarted) | +| void | [torrentStatus(int,int)](#void-torrentstatusint-num_seeders-int-num_peers)| +| void | [started(short)](#void-startedshort-action) | +| void | [canceled(short)](#void-canceledshort-action) | +| void | [finished(QJsonObject , short)](#void-finishedqjsonobject-info-short-action) | +| void | [error(short, short)](#void-errorshort-errorcode-short-action) | +| void | [progress(int, qint64, qint64, double, QString, short)](#void-progressint-percentage--qint64-bytesreceived--qint64-bytestotal--double-speed--qstring-speedunits-short-action) | +| void | [logger(QString, QString)](#void-loggerqstring--qstring) | +| void | [quit()](#void-quit) | + + +## Static Public Members + +| Return Type | Name | +|--------------|------------------------------------------------------| +| QString | [errorCodeToString(short)](#qstring-errorcodetostringshort-errorcode)| +| QString | [errorCodeToDescriptionString(short)](#qstring-errorcodetodescriptionstringshort-errorcode) | + + + +## Actions + +| Variable Name | Value | +|--------------------------------------------------|------ | +| QAppImageUpdate::Action::GetEmbeddedInfo | 0 | +| QAppImageUpdate::Action::CheckForUpdate | 1 | +| QAppImageUpdate::Action::Update | 2 | +| QAppImageUpdate::Action::UpdateWithTorrent | 3 | +| QAppImageUpdate::Action::UpdateWithGUI | 4 | +| QAppImageUpdate::Action::UpdateWithGUIAndTorrent | 5 | +| QAppImageUpdate::Action::Seed | 6 | + + +``` + QAppImageUpdate updater; + updater.start(QAppImageUpdate::Action::CheckForUpdate); // Checks for update. +``` + +## GUI Flags + +| Variable Name | Meaning | Value | +|------------------------------------------------|-----------------------------------------------------------------|-------| +| GuiFlag::ShowProgressDialog | Show the progress dialog during update. | 0x1 | +| GuiFlag::ShowBeforeProgress | Show the progress dialog before the update starts. | 0x2 | +| GuiFlag::ShowUpdateConfirmationDialog | Show a update confirmation dialog. | 0x4 | +| GuiFlag::ShowFinishedDialog | Show a message box when update is finished. | 0x8 | +| GuiFlag::ShowErrorDialog | Show a error message box when update is errored. | 0x10 | +| GuiFlag::NoShowErrorDialogOnPermissionErrors | Do not show error dialog on permission errors. Only emit error.| 0x20 | +| GuiFlag::NotifyWhenNoUpdateIsAvailable | Show a message box when there was no update. | 0x40 | +| GuiFlag::NoRemindMeLaterButton | Do not show 'Remind me later' in the confirmation dialog. | 0x80 | +| GuiFlag::NoSkipThisVersionButton | Do not show 'Skip This Version' in the confirmatino dialog. | 0x100| +| GuiFlag::NoConfirmTorrentUsage | Do not confirm when torrent update is used. | 0x200| +| GuiFlag::Default | Give the default combination of flags | 0x1df| + + + +> The Default flag enables ShowProgressDialog, ShowBeforeProgress, ShowUpdateConfirmationDialog, ShowFinishedDialog, +> ShowErrorDialog, NotifyWhenNoUpdateIsAvailable, NoRemindMeLaterButton, NoSkipThisVersionButton + + + + +## Member Functions Documentation + +### QAppImageUpdate(bool singleThreaded = true, QObject \*parent = nullptr) + +Default Constructor, Constructs the Updater with a assumed AppImage Path +which is most likely the AppImage which is running this updater. +The assumed AppImage Path will only be correct if and only if +this updater is running from a AppImage. + +The default value for **singleThreaded** is **true** but you can set it +to **false** to run all the resource of the updater in a seperate +thread excluding **this class**. + +You can set a **QObject parent** to make use of **Qt's Parent to Children deallocation.** + +``` +QAppImageUpdate updater; +``` + +### QAppImageUpdate(const QString&, bool singleThreaded = true, QObject \*parent = nullptr) + +This is an overloaded constructor, Constructs the Updater with the given QString as the AppImage Path. +If the given QString is not a valid AppImage Path, Then the updater will automatically +guess the AppImage Path, The guessed AppImage Path will be accurate only if the updater is running from +an AppImage. + +The default value for **singleThreaded** is **true** but you can set it to **false** to run all the +resource of the updater in a seperate thread excluding **this class**. + +You can set a **QObject parent** to make use of **Qt's Parent to Children deallocation.** + +### QAppImageUpdate(QFile \*, bool singleThreaded = true, QObject \*parent = nullptr) + +This is an overloaded constructor, Constructs the Updater with the given QFile as the AppImage itself. +If the pointer is invalid or has other sort of read errors, The updater will emit error but when +forced to start, Again the updater guesses the AppImage Path in order to continue with the extraction. +If the guessed AppImage Path is not an AppImage but a normal elf file then this result in a invalid magic +byte error. See [error codes](ErrorCodes.html) for more information. + +The default value for **singleThreaded** is **true** but you can set it to **false** to run all the +resource of the updater in a seperate thread excluding **this class**. + +You can set a **QObject parent** to make use of **Qt's Parent to Children deallocation.** + + +### void setGuiFlag(int flag) + +

[SLOT]

+ +Set the given integer as the flag for GUI update if used. See the [GUI Flags](#gui-flags). + +### void setIcon(QByteArray icon) +

[SLOT]

+ +Set the given icon which is saved as QByteArray. You have to save your ```QPixmap``` as a QByteArray, see [the official docs](https://doc.qt.io/qt-5/qpixmap.html#save-1). + +``` + /// C++ Ref for saving QPixmap as QByteArray + QPixmap pixmap; + QByteArray icon; + QBuffer buffer(&icon); + buffer.open(QIODevice::WriteOnly); + pixmap.save(&buffer, "PNG"); // writes pixmap into bytes in PNG format + + + QAppImageUpdater updater; + updater.setIcon(icon); +``` + +### void start(short action) +

[SLOT]

+ +Starts a specific action as given in the argument of the start slot. +Valid actions are put up in the [Actions table](#actions). + +``` +QAppImageUpdater updater; +updater.start(QAppImageUpdate::Action::CheckForUpdate); +``` + +> When you start QAppImageUpdate::Action::Seed, The finished signal will not be emitted until cancel is requested. + + +### void cancel() +

[SLOT]

+ +Cancels the update. +Emits **canceled(short action)** signal when cancel was successfull. + + +### void setApplicationName(const QString&) +

[SLOT]

+ +Set a application name to use when display GUI dialogs if required. + +> NOTE: This is optional. By default the GUI dialogs uses the AppImage filename. + + + +### void setAppImage(const QString&) +

[SLOT]

+ +Sets the AppImage Path as the given **QString**. + +> WARNING: If you set the AppImage yourself, Then any guessing will not be done and all +> errors relating to find the correct path to AppImage should be handled by the programmer. +> This is seen in the case of AppImageLauncher where the actuall AppImage can be guessed +> by the Updater if do not set the path yourself. + + +### void setAppImage(QFile \*) +

[SLOT]

+ +Sets the given **QFile** as the AppImage itself. + +### void setShowLog(bool) +

[SLOT]

+ +Turns on and off the log printer. + +> Note: logger signal will be emitted all the time if the library is compiled with LOGGING_DISABLED undefined , +setShowLog will not affect this activity at all, But setShowLog will print these log messages +if set to true. + +### void setOutputDirectory(const QString&) +

[SLOT]

+ +Writes the new version of the AppImage to the given Output directory, Assuming the given QString a directory path. +The default is the old version AppImage's directory. + + +### void setProxy(const [QNetworkProxy](https://doc.qt.io/qt-5/qnetworkproxy.html)&) +

[SLOT]

+ +Sets the given [QNetworkProxy](https://doc.qt.io/qt-5/qnetworkproxy.html) as the proxy +to use for all network communication for the updater. + +``` + QNetworkProxy proxy; + proxy.setType(QNetworkProxy::Socks5Proxy); + proxy.setHostName("127.0.0.1"); + proxy.setPort(9050); + + AppImageDeltaRevisioner Revisioner("Ein.AppImage"); + Revisioner.setProxy(proxy); + Revisioner.start(); /* Start the updater */ +``` + + +> WARNING: when using torrent support, only HTTP and SOCKS5 proxy is supported. + + +### void clear() +

[SLOT]

+ +Clears all internal **cache**. + +### void torrentClientStarted() +

[SIGNAL]

+ +Emitted when torrent client is started. + +> NOTE: In builds without torrent support, this signal is never emitted. + + +### void torrentStatus(int num\_seeders, int num\_peers) +

[SIGNAL]

+ +Emitted on every progress of torrent download if BitTorrent is used for +update. + +> NOTE: In builds without torrent support, this signal is never emitted. + + +### void started(short action) +

[SIGNAL]

+ +Emitted when a action is started successfully. + +### void canceled(short action) +

[SIGNAL]

+ +Emitted when the update is canceled successfully. + +### void finished(QJsonObject info, short action) +

[SIGNAL]

+ +Emitted when a action is finished successfully. The given *QJsonObject* is variable and it is dependent +on different actions. + + +The *QJsonObject* will follow the following format with respect to json for ```Action::GetEmbeddedInfo``` action, + + { + "IsEmpty": , + "FileInformation": { + "AppImageFilePath": , + "AppImageSHA1Hash": + }, + "UpdateInformation": { + "transport" : , + + } + } + +**gh-releases-zsync** , + + { + "transport" : "gh-releases-zsync", + "username" : , + "repo" : , + "tag" : , + "filename" : + } + +**bintray-zsync** , + + { + "transport" : "bintray-zsync" , + "username" : , + "repo" : , + "packageName" : , + "filename" : + } + +**zsync**, + + { + "transport" : "zsync", + "zsyncUrl" : + } + + + + +The *QJsonObject* will follow the following format with respect to json for ```Action::CheckForUpdate``` action, + + { + "UpdateAvailable": , + "AbsolutePath" : , + "RemoteTargetFileName": , + "LocalSha1Hash" : , + "RemoteSha1Hash" : , + "ReleaseNotes": , + "TorrentSupported": , + "TorrentFileUrl": + } + + + + +The *QJsonObject* will follow the following format with respect to json for ```Action::Update``` action(And all other update action variants), + + { + "OldVersionPath": , + "NewVersionPath": , + "UsedTorrent": , + "TorrentFileUrl": + } + + + +### void error(short errorCode, short action) +

[SIGNAL]

+ +Emitted when the updater is errored. The given short integer is the error code. +See [error codes](ErrorCodes.html). + + +### void progress(int percentage , qint64 bytesReceived , qint64 bytesTotal , double speed , QString speedUnits, short action) +

[SIGNAL]

+ +The updater's progress is emitted through this unified signal. + +**Where** , + +| Variable | Description | +|----------------|------------------------------------------------------------------| +| percentage | % Finished revising the latest AppImage. | +| bytesReceived | The received bytes of the latest AppImage. | +| bytesTotal | The total bytes of the latest AppImage. | +| speed | The transfer speed value. | +| speedUnit | The transfer speed unit(e.g. KiB/s , etc... ) for **speed**. | +| action | The action this progress refers to. | + + +### void logger(QString , QString) +

[SIGNAL]

+ +Emitted when the updater issues a log message with the *first QString* as the log message and +the *second QString* as the path to the respective AppImage. + + +### void quit() +

[SIGNAL]

+ +Emitted when it's required quit the current application when using the GUI updater. + + +## QString errorCodeToString(short errorCode) +

[STATIC]

+ +Returns the error as a string denoting the error code. + +### QString errorCodeToDescriptionString(short errorCode) +

[STATIC]

+ +Returns a human readable error string for the given error code. diff --git a/website/versioned_docs/version-2.0.1/PluginInterface.md b/website/versioned_docs/version-2.0.1/PluginInterface.md new file mode 100644 index 0000000..bd7af7a --- /dev/null +++ b/website/versioned_docs/version-2.0.1/PluginInterface.md @@ -0,0 +1,379 @@ +--- +id: version-2.0.1-PluginInterface +title: QAppImageUpdate Plugin Interface +sidebar_label: Qt Plugin Interface +original_id: PluginInterface +--- + +A plugin interface is a specification of public slots and signals that can be used to access +the functionality of the plugin itself. The interface is not bound to any specific programming +language and easily translates to any Qt bindings and programming language. + +All slots are [reentrant](https://doc.qt.io/qt-5/threads-reentrancy.html) and thread safe. + +Please refer the C++ documentation for info on how the slots act. + +> IMPORTANT: You have to start your Qt event loop for AppImageUpdaterBridge to function. + +### A note on Data Types + +Since plugins are not C++ specific, The data types are vaguely defined. +In dynamic languages like python, you can just use native data types. (i.e) For QString, you can use str or QString from your Qt binding itself. + +I'm not sure about other Qt bindings, So help is much welcomed. + +## Slots + +| Name | Description | +|-------------------------------|---------------------------------| +| [setGuiFlag(int)](#setguiflagint-flag) | Set GUI Flag. | +| [setIcon(QByteArray)](#seticonqbytearray-icon) | Set Icon for GUI Update. | +| [start(short)](#startshort-action) | Starts the given action. | +| [cancel()](#cancel) | Cancels current update process. | +| [setApplicationName(QString)](#setapplicationnameqstring) | Sets the Application Name in GUI dialogs. | +| [setAppImagePath(QString)](#setappimagepathqstring) | Assume the given string as path to AppImage to update. | +| [setAppImageFile(QFile\*)](#setappimagefileqfile) | Assume the given QFile as the AppImage to update. | +| [setShowLog(bool)](#setshowlogbool) | If the given boolean is true then prints log. | +| [setOutputDirectory(QString)](#setoutputdirectoryqstring) | Set the output directory as given string. | +| [setProxy(QNetworkProxy)](#setproxyqnetworkproxyhttpsdocqtioqt-5qnetworkproxyhtml) | Use proxy as given in QNetworkProxy object. | +| [getConstant(QString)](#int-getconstantconst-qstring) | Get the constant with respect to the string. | +| [getObject()](#qobject-getobject) | Get QObject to slots to connect to this plugin. | +| [clear()](#clear) | Clears internal cache and stores. | +| [errorCodeToString(short)](#qstring-errorcodetostringshort-errorcode) | Convert the given error code to string. | +| [errorCodeToDescriptionString(short)](#qstring-errorcodetodescriptionstringshort-errorcode) | Convert the given error code to description. | + +## Signals + +| Name | Description | +|-----------------------------------|----------------------------------------------| +| [torrentClientStarted()](#void-torrentclientstarted)| Emitted when torrent client is started. | +| [torrentStatus(int,int)](#void-torrentstatusint-num_seeders-int-num_peers)| Emitted on every progress of download. | +| [started(short)](#startedshort) | Emitted when a action is started. | +| [canceled(short)](#canceledshort) | Emitted when a action is canceled. | +| [finished(QJsonObject , short)](#finishedqjsonobject--short) | Emitted when a action is finished. | +| [error(short, short)](#errorshort-errorcode-short-action) | Emitted when some error occurs in an action. | +| [progress(int, qint64, qint64, double, QString, short)](#progressint-percentage--qint64-bytesreceived--qint64-bytestotal--double-speed--qstring-speedunits-short-action) | Emitted on progress of a action. | +| [logger(QString, QString)](#loggerqstring--qstring) | See here for more information. | +| [quit()](#quit) | Emitted when it's desired to quit current application. | + +## Actions + +| Variable Name | Value | +|---------------------------------|------ | +| Action::GetEmbeddedInfo | 0 | +| Action::CheckForUpdate | 1 | +| Action::Update | 2 | +| Action::UpdateWithTorrent | 3 | +| Action::UpdateWithGUI | 4 | +| Action::UpdateWithGUIAndTorrent | 5 | +| Action::Seed | 6 | + + +You can use **getConstant(QString)** method of the plugin interface to get the value for a action. + +``` + # PyQt5 Code + plugin_instance.getConstant("Action::GetEmbeddedInfo") # = 0 +``` + +## GUI Flags + +| Variable Name | Meaning | Value | +|------------------------------------------------|-----------------------------------------------------------------|-------| +| GuiFlag::ShowProgressDialog | Show the progress dialog during update. | 0x1 | +| GuiFlag::ShowBeforeProgress | Show the progress dialog before the update starts. | 0x2 | +| GuiFlag::ShowUpdateConfirmationDialog | Show a update confirmation dialog. | 0x4 | +| GuiFlag::ShowFinishedDialog | Show a message box when update is finished. | 0x8 | +| GuiFlag::ShowErrorDialog | Show a error message box when update is errored. | 0x10 | +| GuiFlag::NoShowErrorDialogOnPermissionErrors | Do not show error dialog on permission errors. Only emit error.| 0x20 | +| GuiFlag::NotifyWhenNoUpdateIsAvailable | Show a message box when there was no update. | 0x40 | +| GuiFlag::NoRemindMeLaterButton | Do not show 'Remind me later' in the confirmation dialog. | 0x80 | +| GuiFlag::NoSkipThisVersionButton | Do not show 'Skip This Version' in the confirmatino dialog. | 0x100| +| GuiFlag::NoConfirmTorrentUsage | Do not confirm when torrent update is used. | 0x200| +| GuiFlag::Default | Give the default combination of flags | 0x1df| + + +You can use **getConstant(QString)** method of the plugin interface to get the value for a gui flag same as with +actions. + +``` + # PyQt5 Code + plugin_instance.getConstant("GuiFlag::NoConfirmTorrentUsage") # = 0x200 +``` + + +> The Default flag enables ShowProgressDialog, ShowBeforeProgress, ShowUpdateConfirmationDialog, ShowFinishedDialog, +> ShowErrorDialog, NotifyWhenNoUpdateIsAvailable, NoRemindMeLaterButton, NoSkipThisVersionButton + + +## Documentation + + +### setGuiFlag(int flag) + +

[SLOT]

+ +Set the given integer as the flag for GUI update if used. + +### setIcon(QByteArray icon) +

[SLOT]

+ +Set the given icon which is saved as QByteArray. You have to save your ```QPixmap``` as a QByteArray, see [the official docs](https://doc.qt.io/qt-5/qpixmap.html#save-1). + +``` + /// C++ Ref for saving QPixmap as QByteArray + QPixmap pixmap; + QByteArray icon; + QBuffer buffer(&icon); + buffer.open(QIODevice::WriteOnly); + pixmap.save(&buffer, "PNG"); // writes pixmap into bytes in PNG format + + + QAppImageUpdater updater; + updater.setIcon(icon); +``` + +### start(short action) +

[SLOT]

+ +Starts the given action in the argument. +Emits **started(short action)** signal when starts. + +The short integer should be one of the possible actions as given in the [Actions table](#actions). +One has to use **getConstant(QString)** method to get a constant. + + +> Please start your QApplication event loop to get effect from the updater. + + +> When you start Action::Seed, The finished signal will not be emitted until cancel is requested. + + +``` + # PyQt5 code + updater = plugin_loader.instance() + updater.setAppImagePath("Some.AppImage") + + def handleFinish(jsonObj, action): + if action == updater.getConstant("Action::CheckForUpdate"): + if jsonObj["UpdateAvailable"].toBool(): + updater.start(updater.getConstant("Action::Update") + return; + if action == updater.getConstant("Action::Update") + app.quit() + + updater.finished.connect(handleFinish) + + updater.start(updater.getConstant("Action::CheckForUpdate")) +``` + +> Important Note: You should also call clear and set the settings again if you want to clear the cache. + + +### cancel() +

[SLOT]

+ +Cancels the current action. +Emits **canceled(short)** signal when cancel for a action was successfull. + + +### setApplicationName(QString) +

[SLOT]

+ +Sets the given string as the Application Name which will be used in GUI dialogs. + +> NOTE: This is optional and by default the updater uses the AppImage filename. + + +### setAppImagePath(QString) +

[SLOT]

+ +Sets the AppImage Path as the given **QString**. + + +### setAppImageFile(QFile\*) +

[SLOT]

+ +Sets the given QFile as the AppImage itself. + + +### setShowLog(bool) +

[SLOT]

+ +Turns on and off the log printer. + +> Note: logger signal will be emitted all the time if the library is compiled with LOGGING_DISABLED undefined, +setShowLog will not affect this activity at all, But setShowLog will print these log messages +if set to true. + +### setOutputDirectory(QString) +

[SLOT]

+ +Writes the new version of the AppImage to the given Output directory , Assuming the given QString a directory path. +The default is the old version AppImage's directory. + + +### setProxy([QNetworkProxy](https://doc.qt.io/qt-5/qnetworkproxy.html)) +

[SLOT]

+ +Sets the given [QNetworkProxy](https://doc.qt.io/qt-5/qnetworkproxy.html) as the proxy + +> WARNING: when using torrent support, only HTTP and SOCKS5 proxy is supported. + + +### clear() +

[SLOT]

+ +Clears all internal **cache** and stores. + + +### void torrentClientStarted() +

[SIGNAL]

+ +Emitted when torrent client is started. + +> NOTE: In builds without torrent support, this signal is never emitted. + + +### void torrentStatus(int num\_seeders, int num\_peers) +

[SIGNAL]

+ +Emitted on every progress of torrent download if BitTorrent is used for +update. + +> NOTE: In builds without torrent support, this signal is never emitted. + + +### started(short) +

[SIGNAL]

+ +Emitted when a action is started, with the argument denoting the action which is started. + +### canceled(short) +

[SIGNAL]

+ +Emitted when a action is canceled, with the argument denoting the action which is canceled. + + +### finished(QJsonObject , short) +

[SIGNAL]

+ +Emitted when a action is finished successfully. The given *QJsonObject* is variable and it is dependent +on different actions. + + +The *QJsonObject* will follow the following format with respect to json for ```Action::GetEmbeddedInfo``` action, + + { + "IsEmpty": , + "FileInformation": { + "AppImageFilePath": , + "AppImageSHA1Hash": + }, + "UpdateInformation": { + "transport" : , + + } + } + +**gh-releases-zsync** , + + { + "transport" : "gh-releases-zsync", + "username" : , + "repo" : , + "tag" : , + "filename" : + } + +**bintray-zsync** , + + { + "transport" : "bintray-zsync" , + "username" : , + "repo" : , + "packageName" : , + "filename" : + } + +**zsync**, + + { + "transport" : "zsync", + "zsyncUrl" : + } + + + + +The *QJsonObject* will follow the following format with respect to json for ```Action::CheckForUpdate``` action, + + { + "UpdateAvailable": , + "AbsolutePath" : , + "LocalSha1Hash" : , + "RemoteSha1Hash" : , + "ReleaseNotes": , + "TorrentSupported": + } + + + + +The *QJsonObject* will follow the following format with respect to json for ```Action::Update``` action(And all other update action variants), + + { + "OldVersionPath": , + "NewVersionPath": , + "UsedTorrent": [SIGNAL]

+ +Emitted when the updater is errored. See [error codes](AppImageUpdaterBridgeErrorCodes.html). + + +### progress(int percentage , qint64 bytesReceived , qint64 bytesTotal , double speed , QString speedUnits, short action) +

[SIGNAL]

+ +The updater's progress is emitted through this unified signal. + +**Where** , + +| Variable | Description | +|----------------|------------------------------------------------------------------| +| percentage | % Finished revising the latest AppImage. | +| bytesReceived | The received bytes of the latest AppImage. | +| bytesTotal | The total bytes of the latest AppImage. | +| speed | The transfer speed value. | +| speedUnit | The transfer speed unit(e.g. KiB/s , etc... ) for **speed**. | +| action | The action this progress refers to. | + +### logger(QString , QString) +

[SIGNAL]

+ +Emitted when the updater issues a log message with the *first QString* as the log message and +the *second QString* as the path to the respective AppImage. + +### quit() +

[SIGNAL]

+ +Emitted when it's desired to quit the current application when using GUI update. + + +### QObject\* getObject() + +Returns the QObject pointer. Useful when using this plugin in C++. + +### int getConstant(const QString&) + +Returns the constant value as per values in [Action table](#actions) and [GUI Flags](#gui-flags). + +### QString errorCodeToString(short errorCode) + +Returns the error as a string denoting the error code. + +### QString errorCodeToDescriptionString(short errorCode) + +Returns a human readable error string for the given error code. diff --git a/website/versions.json b/website/versions.json index a2b2adf..581a632 100644 --- a/website/versions.json +++ b/website/versions.json @@ -1,4 +1,5 @@ [ + "2.0.1", "2.0.0", "1.1.9" ]