BaseJob: "background" switch; more extensive error reporting

Running a request in background, aside from some tweaks on the network
layer (see QNetworkRequest::BackgroundRequestAttribute), allows to
distinguish jobs not immediately caused by user interaction (such as
fetching thumbnails). This can be used to show or not show certain
notifications in UI of clients.

Error reporting has been extended with more methods:
errorCaption() - a human-readable phrase calculated from the status
code; intended to be shown as a dialog caption and in similar
situations.
errorRawData() - former errorDetails(), returns the raw response from
the server.
errorUrl() - returns a URL that may be useful with the error (e.g. for
the upcoming "consent not given" error, this will have the policy URL).
Connection::resultFailed() - a new signal emitted when _any_
BaseJob::failure() is emitted (enables centralised error handling
across all network requests in clients).

As a part of matching changes in Connection, callApi has an overload
that allows to specify the policy; a custom enum instead of bool has
been chosen for the parameter type, to avoid clashes with (arbitrary)
types of job parameters.

1 files changed, 54 insertions, 11 deletions

diff --git a/lib/connection.h b/lib/connection.h
index 4ce1d127..197e4785 100644
--- a/lib/connection.h
+++ b/lib/connection.h
@@ -46,6 +46,13 @@ namespace QMatrixClient
     class GetContentJob;
     class DownloadFileJob;
 
+    /** Enumeration with flags defining the network job running policy
+     * So far only background/foreground flags are available.
+     *
+     * \sa Connection::callApi
+     */
+    enum RunningPolicy { InForeground = 0x0, InBackground = 0x1 };
+
     class Connection: public QObject {
             Q_OBJECT
 
@@ -191,20 +198,39 @@ namespace QMatrixClient
             bool cacheState() const;
             void setCacheState(bool newValue);
 
-            /**
+            /** Start a job of a specified type with specified arguments and policy
+             *
              * This is a universal method to start a job of a type passed
-             * as a template parameter. Arguments to callApi() are arguments
-             * to the job constructor _except_ the first ConnectionData*
-             * argument - callApi() will pass it automatically.
+             * as a template parameter. The policy allows to fine-tune the way
+             * the job is executed - as of this writing it means a choice
+             * between "foreground" and "background".
+             *
+             * \param runningPolicy controls how the job is executed
+             * \param jobArgs arguments to the job constructor
+             *
+             * \sa BaseJob::isBackground. QNetworkRequest::BackgroundRequestAttribute
              */
             template <typename JobT, typename... JobArgTs>
-            JobT* callApi(JobArgTs&&... jobArgs) const
+            JobT* callApi(RunningPolicy runningPolicy,
+                          JobArgTs&&... jobArgs) const
             {
                 auto job = new JobT(std::forward<JobArgTs>(jobArgs)...);
-                job->start(connectionData());
+                connect(job, &BaseJob::failure, this, &Connection::requestFailed);
+                job->start(connectionData(), runningPolicy&InBackground);
                 return job;
             }
 
+            /** Start a job of a specified type with specified arguments
+             *
+             * This is an overload that calls the job with "foreground" policy.
+             */
+            template <typename JobT, typename... JobArgTs>
+            JobT* callApi(JobArgTs&&... jobArgs) const
+            {
+                return callApi<JobT>(InForeground,
+                                     std::forward<JobArgTs>(jobArgs)...);
+            }
+
             /** Generates a new transaction id. Transaction id's are unique within
              * a single Connection object
              */
@@ -246,12 +272,12 @@ namespace QMatrixClient
             void stopSync();
 
             virtual MediaThumbnailJob* getThumbnail(const QString& mediaId,
-                                                    QSize requestedSize) const;
+                QSize requestedSize, RunningPolicy policy = InBackground) const;
             MediaThumbnailJob* getThumbnail(const QUrl& url,
-                                            QSize requestedSize) const;
+                QSize requestedSize, RunningPolicy policy = InBackground) const;
             MediaThumbnailJob* getThumbnail(const QUrl& url,
-                                            int requestedWidth,
-                                            int requestedHeight) const;
+                int requestedWidth, int requestedHeight,
+                RunningPolicy policy = InBackground) const;
 
             // QIODevice* should already be open
             UploadContentJob* uploadContent(QIODevice* contentSource,
@@ -349,9 +375,26 @@ namespace QMatrixClient
             void homeserverChanged(QUrl baseUrl);
 
             void connected();
-            void reconnected(); //< Unused; use connected() instead
+            void reconnected(); //< \deprecated Use connected() instead
             void loggedOut();
             void loginError(QString message, QByteArray details);
+
+            /** A network request (job) failed
+             *
+             * @param request - the pointer to the failed job
+             */
+            void requestFailed(BaseJob* request);
+
+            /** A network request (job) failed due to network problems
+             *
+             * This is _only_ emitted when the job will retry on its own;
+             * once it gives up, requestFailed() will be emitted.
+             *
+             * @param message - message about the network problem
+             * @param details - raw error details, if any available
+             * @param retriesTaken - how many retries have already been taken
+             * @param nextRetryInMilliseconds - when the job will retry again
+             */
             void networkError(QString message, QByteArray details,
                               int retriesTaken, int nextRetryInMilliseconds);