Add StartLater / StartImmediately distinction

qgis · Jul 30, 2021 · 014a4aa · 014a4aa
1 parent 3010b2f
commit 014a4aa
Show file tree

Hide file tree

Showing 9 changed files with 252 additions and 53 deletions.
diff --git a/python/core/auto_additions/qgis.py b/python/core/auto_additions/qgis.py
@@ -513,3 +513,9 @@
 Qgis.ContentStatus.__doc__ = 'Status for fetched or stored content\n\n.. versionadded:: 3.22\n\n' + '* ``NotStarted``: ' + Qgis.ContentStatus.NotStarted.__doc__ + '\n' + '* ``OnGoing``: ' + Qgis.ContentStatus.OnGoing.__doc__ + '\n' + '* ``Finished``: ' + Qgis.ContentStatus.Finished.__doc__ + '\n' + '* ``Failed``: ' + Qgis.ContentStatus.Failed.__doc__ + '\n' + '* ``Canceled``: ' + Qgis.ContentStatus.Canceled.__doc__
 # --
 Qgis.ContentStatus.baseClass = Qgis
+# monkey patching scoped based enum
+Qgis.ExternalStorageContentMode.StartLater.__doc__ = "Do not start immediately to fetch/store to properly connect the fetched/stored signal"
+Qgis.ExternalStorageContentMode.StartImmediately.__doc__ = "Fetching/Storing will start immediately, not need to run fetch/store method"
+Qgis.ExternalStorageContentMode.__doc__ = 'Status for fetched or stored content\n\n.. versionadded:: 3.22\n\n' + '* ``StartLater``: ' + Qgis.ExternalStorageContentMode.StartLater.__doc__ + '\n' + '* ``StartImmediately``: ' + Qgis.ExternalStorageContentMode.StartImmediately.__doc__
+# --
+Qgis.ExternalStorageContentMode.baseClass = Qgis
diff --git a/python/core/auto_generated/externalstorage/qgsexternalstorage.sip.in b/python/core/auto_generated/externalstorage/qgsexternalstorage.sip.in
@@ -31,34 +31,54 @@ and registered in :py:class:`QgsExternalStorageRegistry`.
 Unique identifier of the external storage type.
 %End
 
-    virtual QgsExternalStorageStoredContent *store( const QString &filePath, const QString &url, const QString &authcfg = QString() ) const = 0 /Factory/;
+    QgsExternalStorageStoredContent *store( const QString &filePath, const QString &url, const QString &authCfg = QString(), Qgis::ExternalStorageContentMode storingMode = Qgis::ExternalStorageContentMode::StartLater ) const /Factory/;
 %Docstring
 Stores file ``filePath`` to the ``url`` for this project external storage.
 Storing process is run in background.
 Returns a :py:class:`QgsExternalStorageStoredContent` to follow the status of the stored resource.
 
-After using this method, user should check if the returned content is not already finished
-(storing could be instantaneous, if file has already been stored for instance) and then wait
-for :py:func:`QgsExternalStorageStoredContent.stored()`, :py:func:`QgsExternalStorageStoredContent.errorOccurred()` or
-:py:func:`QgsExternalStorageStoredContent.canceled()` signals.
+``storingMode`` defines if the download will start immediately or shall be manually triggered
+calling :py:func:`QgsExternalStorageStoredContent.store()`. User should use
+Qgis.ExternalStorageContentMode.StartLater if he needs to connect the :py:func:`~QgsExternalStorage.stored` signal.
 
-It's possible to give ``authcfg`` authentication configuration id in case its needed.
+After using this method, user wait for :py:func:`QgsExternalStorageStoredContent.stored()`,
+:py:func:`QgsExternalStorageStoredContent.errorOccurred()` or :py:func:`QgsExternalStorageStoredContent.canceled()` signals.
+
+It's possible to give ``authCfg`` authentication configuration id in case its needed.
 
 Caller takes ownership of the returned symbol.
 %End
 
-    virtual QgsExternalStorageFetchedContent *fetch( const QString &url, const QString &authcfg = QString() ) const = 0 /Factory/;
+    QgsExternalStorageFetchedContent *fetch( const QString &url, const QString &authCfg = QString(), Qgis::ExternalStorageContentMode fetchingMode = Qgis::ExternalStorageContentMode::StartLater ) const /Factory/;
 %Docstring
 Fetches file from ``url`` for this project external storage.
 Fetching process is run in background.
 Returns a :py:class:`QgsExternalStorageFetchedContent` to follow the status of the fetched resource.
 
-After using this method, user should check if the returned content is not already finished
-(fetching could be instantaneous, if file has already been fetched and cached for instance)
-and then wait for :py:func:`QgsExternalStorageStoredContent.fetched()`, :py:func:`QgsExternalStorageStoredContent.errorOccurred()` or
-:py:func:`QgsExternalStorageStoredContent.canceled()` signals.
+``fetchingMode`` defines if the download will start immediately or shall be manually triggered
+calling :py:func:`QgsExternalStorageFetchedContent.fetch()`. User should use
+Qgis.ExternalStorageContentMode.StartLater if he needs to connect the :py:func:`~QgsExternalStorage.fetched` signal.
+
+After using this method, user should wait for :py:func:`QgsExternalStorageStoredContent.fetched()`,
+:py:func:`QgsExternalStorageStoredContent.errorOccurred()` or :py:func:`QgsExternalStorageStoredContent.canceled()` signals.
+
+It's possible to give ``authCfg`` authentication configuration id in case its needed.
+%End
+
+  protected:
+
+    virtual QgsExternalStorageStoredContent *doStore( const QString &filePath, const QString &url, const QString &authCfg = QString() ) const = 0 /Factory/;
+%Docstring
+Stores file ``filePath`` to the ``url`` using ``authCfg`` authentication for this project external storage.
+
+.. seealso:: :py:func:`QgsExternalStorage.store`
+%End
+
+    virtual QgsExternalStorageFetchedContent *doFetch( const QString &url, const QString &authCfg = QString() ) const = 0 /Factory/;
+%Docstring
+Fetches file from ``url`` using ``authCfg`` for this project external storage.
 
-It's possible to give ``authcfg`` authentication configuration id in case its needed.
+.. seealso:: :py:func:`QgsExternalStorage.fetch`
 %End
 };
 
@@ -135,6 +155,11 @@ Class for :py:class:`QgsExternalStorage` fetched content
     virtual QString filePath() const = 0;
 %Docstring
 Returns fetched resource file path
+%End
+
+    virtual void fetch() = 0;
+%Docstring
+Starts fetching
 %End
 
   signals:
@@ -161,6 +186,11 @@ Class for :py:class:`QgsExternalStorage` stored content
     virtual QString url() const = 0;
 %Docstring
 Returns stored resource URL
+%End
+
+    virtual void store() = 0;
+%Docstring
+Starts storing
 %End
 
   signals:

diff --git a/python/core/auto_generated/qgis.sip.in b/python/core/auto_generated/qgis.sip.in
@@ -378,6 +378,12 @@ The development version
       Canceled,
     };
 
+    enum class ExternalStorageContentMode
+    {
+      StartLater,
+      StartImmediately,
+    };
+
     static const double DEFAULT_SEARCH_RADIUS_MM;
 
     static const float DEFAULT_MAPTOPIXEL_THRESHOLD;

diff --git a/src/core/externalstorage/qgsexternalstorage.cpp b/src/core/externalstorage/qgsexternalstorage.cpp
@@ -31,3 +31,21 @@ const QString &QgsExternalStorageContent::errorString() const
 {
   return mErrorString;
 };
+
+QgsExternalStorageStoredContent *QgsExternalStorage::store( const QString &filePath, const QString &url, const QString &authCfg, Qgis::ExternalStorageContentMode storingMode ) const
+{
+  QgsExternalStorageStoredContent *content = doStore( filePath, url, authCfg );
+  if ( storingMode == Qgis::ExternalStorageContentMode::StartImmediately )
+    content->store();
+
+  return content;
+}
+
+QgsExternalStorageFetchedContent *QgsExternalStorage::fetch( const QString &url, const QString &authCfg, Qgis::ExternalStorageContentMode fetchingMode ) const
+{
+  QgsExternalStorageFetchedContent *content = doFetch( url, authCfg );
+  if ( fetchingMode == Qgis::ExternalStorageContentMode::StartImmediately )
+    content->fetch();
+
+  return content;
+}
diff --git a/src/core/externalstorage/qgsexternalstorage.h b/src/core/externalstorage/qgsexternalstorage.h
@@ -52,30 +52,48 @@ class CORE_EXPORT QgsExternalStorage
      * Storing process is run in background.
      * Returns a QgsExternalStorageStoredContent to follow the status of the stored resource.
      *
-     * After using this method, user should check if the returned content is not already finished
-     * (storing could be instantaneous, if file has already been stored for instance) and then wait
-     * for QgsExternalStorageStoredContent::stored(), QgsExternalStorageStoredContent::errorOccurred() or
-     * QgsExternalStorageStoredContent::canceled() signals.
+     * \a storingMode defines if the download will start immediately or shall be manually triggered
+     * calling QgsExternalStorageStoredContent::store(). User should use
+     * Qgis::ExternalStorageContentMode::StartLater if he needs to connect the stored() signal.
      *
-     * It's possible to give \a authcfg authentication configuration id in case its needed.
+     * After using this method, user wait for QgsExternalStorageStoredContent::stored(),
+     * QgsExternalStorageStoredContent::errorOccurred() or QgsExternalStorageStoredContent::canceled() signals.
+     *
+     * It's possible to give \a authCfg authentication configuration id in case its needed.
      *
      * Caller takes ownership of the returned symbol.
      */
-    virtual QgsExternalStorageStoredContent *store( const QString &filePath, const QString &url, const QString &authcfg = QString() ) const = 0 SIP_FACTORY;
+    QgsExternalStorageStoredContent *store( const QString &filePath, const QString &url, const QString &authCfg = QString(), Qgis::ExternalStorageContentMode storingMode = Qgis::ExternalStorageContentMode::StartLater ) const SIP_FACTORY;
 
     /**
      * Fetches file from \a url for this project external storage.
      * Fetching process is run in background.
      * Returns a QgsExternalStorageFetchedContent to follow the status of the fetched resource.
      *
-     * After using this method, user should check if the returned content is not already finished
-     * (fetching could be instantaneous, if file has already been fetched and cached for instance)
-     * and then wait for QgsExternalStorageStoredContent::fetched(), QgsExternalStorageStoredContent::errorOccurred() or
-     * QgsExternalStorageStoredContent::canceled() signals.
+     * \a fetchingMode defines if the download will start immediately or shall be manually triggered
+     * calling QgsExternalStorageFetchedContent::fetch(). User should use
+     * Qgis::ExternalStorageContentMode::StartLater if he needs to connect the fetched() signal.
+     *
+     * After using this method, user should wait for QgsExternalStorageStoredContent::fetched(),
+     * QgsExternalStorageStoredContent::errorOccurred() or QgsExternalStorageStoredContent::canceled() signals.
      *
-     * It's possible to give \a authcfg authentication configuration id in case its needed.
+     * It's possible to give \a authCfg authentication configuration id in case its needed.
+     */
+    QgsExternalStorageFetchedContent *fetch( const QString &url, const QString &authCfg = QString(), Qgis::ExternalStorageContentMode fetchingMode = Qgis::ExternalStorageContentMode::StartLater ) const SIP_FACTORY;
+
+  protected:
+
+    /**
+     * Stores file \a filePath to the \a url using \a authCfg authentication for this project external storage.
+     * \see QgsExternalStorage::store()
+     */
+    virtual QgsExternalStorageStoredContent *doStore( const QString &filePath, const QString &url, const QString &authCfg = QString() ) const = 0 SIP_FACTORY;
+
+    /**
+     * Fetches file from \a url using \a authCfg for this project external storage.
+     * \see QgsExternalStorage::fetch()
      */
-    virtual QgsExternalStorageFetchedContent *fetch( const QString &url, const QString &authcfg = QString() ) const = 0 SIP_FACTORY;
+    virtual QgsExternalStorageFetchedContent *doFetch( const QString &url, const QString &authCfg = QString() ) const = 0 SIP_FACTORY;
 };
 
 /**
@@ -154,6 +172,11 @@ class CORE_EXPORT QgsExternalStorageFetchedContent : public QgsExternalStorageCo
      */
     virtual QString filePath() const = 0;
 
+    /**
+     * Starts fetching
+     */
+    virtual void fetch() = 0;
+
   signals:
 
     /**
@@ -179,6 +202,11 @@ class CORE_EXPORT QgsExternalStorageStoredContent : public QgsExternalStorageCon
      */
     virtual QString url() const = 0;
 
+    /**
+     * Starts storing
+     */
+    virtual void store() = 0;
+
   signals:
 
     /**

diff --git a/src/core/externalstorage/qgssimplecopyexternalstorage.cpp b/src/core/externalstorage/qgssimplecopyexternalstorage.cpp
@@ -42,9 +42,11 @@ QgsSimpleCopyExternalStorageStoredContent::QgsSimpleCopyExternalStorageStoredCon
   {
     emit progressChanged( progress );
   } );
+}
 
+void QgsSimpleCopyExternalStorageStoredContent::store()
+{
   mStatus = Qgis::ContentStatus::OnGoing;
-
   QgsApplication::instance()->taskManager()->addTask( mCopyTask );
 }
 
@@ -69,35 +71,41 @@ QString QgsSimpleCopyExternalStorageStoredContent::url() const
 }
 
 QgsSimpleCopyExternalStorageFetchedContent::QgsSimpleCopyExternalStorageFetchedContent( const QString &filePath )
+  : mFilePath( filePath )
+{
+}
+
+void QgsSimpleCopyExternalStorageFetchedContent::fetch()
 {
   // no fetching process, we read directly from its location
-  if ( !QFileInfo::exists( filePath ) )
+  if ( !QFileInfo::exists( mFilePath ) )
   {
-    reportError( tr( "File '%1' does not exist" ).arg( filePath ) );
+    reportError( tr( "File '%1' does not exist" ).arg( mFilePath ) );
   }
   else
   {
     mStatus = Qgis::ContentStatus::Finished;
-    mFilePath = filePath;
+    mResultFilePath = mFilePath;
+    emit fetched();
   }
 }
 
 QString QgsSimpleCopyExternalStorageFetchedContent::filePath() const
 {
-  return mFilePath;
+  return mResultFilePath;
 }
 
 QString QgsSimpleCopyExternalStorage::type() const
 {
   return QStringLiteral( "SimpleCopy" );
 };
 
-QgsExternalStorageStoredContent *QgsSimpleCopyExternalStorage::store( const QString &filePath, const QString &url, const QString &authcfg ) const
+QgsExternalStorageStoredContent *QgsSimpleCopyExternalStorage::doStore( const QString &filePath, const QString &url, const QString &authcfg ) const
 {
   return new QgsSimpleCopyExternalStorageStoredContent( filePath, url, authcfg );
 };
 
-QgsExternalStorageFetchedContent *QgsSimpleCopyExternalStorage::fetch( const QString &url, const QString &authConfig ) const
+QgsExternalStorageFetchedContent *QgsSimpleCopyExternalStorage::doFetch( const QString &url, const QString &authConfig ) const
 {
   Q_UNUSED( authConfig );
 

diff --git a/src/core/externalstorage/qgssimplecopyexternalstorage_p.h b/src/core/externalstorage/qgssimplecopyexternalstorage_p.h
@@ -40,9 +40,9 @@ class CORE_EXPORT QgsSimpleCopyExternalStorage : public QgsExternalStorage
 
     QString type() const override;
 
-    QgsExternalStorageStoredContent *store( const QString &filePath, const QString &url, const QString &authcfg = QString() ) const override;
+    QgsExternalStorageStoredContent *doStore( const QString &filePath, const QString &url, const QString &authcfg = QString() ) const override;
 
-    QgsExternalStorageFetchedContent *fetch( const QString &url, const QString &authConfig = QString() ) const override;
+    QgsExternalStorageFetchedContent *doFetch( const QString &url, const QString &authConfig = QString() ) const override;
 };
 
 /**
@@ -63,6 +63,8 @@ class QgsSimpleCopyExternalStorageStoredContent  : public QgsExternalStorageStor
 
     QString url() const override;
 
+    void store() override;
+
   private:
 
     QPointer<QgsCopyFileTask> mCopyTask;
@@ -85,9 +87,12 @@ class QgsSimpleCopyExternalStorageFetchedContent : public QgsExternalStorageFetc
 
     QString filePath() const override;
 
+    void fetch() override;
+
   private:
 
     QString mFilePath;
+    QString mResultFilePath;
 };
 
 

diff --git a/src/core/qgis.h b/src/core/qgis.h
@@ -547,6 +547,17 @@ class CORE_EXPORT Qgis
     };
     Q_ENUM( ContentStatus )
 
+    /*
+     * Status for fetched or stored content
+     * \since QGIS 3.22
+     */
+    enum class ExternalStorageContentMode : int
+    {
+      StartLater, //!< Do not start immediately to fetch/store to properly connect the fetched/stored signal
+      StartImmediately, //!< Fetching/Storing will start immediately, not need to run fetch/store method
+    };
+    Q_ENUM( ExternalStorageContentMode )
+
     /**
      * Babel GPS format capabilities.
      *