qgsproviderregistry.h

Go to the documentation of this file.

/***************************************************************************
                    qgsproviderregistry.h  -  Singleton class for
                    registering data providers.
                             -------------------
    begin                : Sat Jan 10 2004
    copyright            : (C) 2004 by Gary E.Sherman
    email                : sherman at mrcc.com
 ***************************************************************************/
 
/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/
 
#ifndef QGSPROVIDERREGISTRY_H
#define QGSPROVIDERREGISTRY_H
 
#include <map>
 
#include "qgis_core.h"
#include "qgis_sip.h"
#include "qgsdataprovider.h"
 
#include <QDir>
#include <QLibrary>
#include <QString>
 
using namespace Qt::StringLiterals;
 
class QgsProviderMetadata;
class QgsVectorLayer;
class QgsCoordinateReferenceSystem;
class QgsDataItemProvider;
class QgsDataItem;
class QgsRasterDataProvider;
class QgsTransaction;
class QgsFields;
class QgsProviderSublayerDetails;
class QgsFeedback;
class QgsEmptyLayerCreationResult;

class CORE_EXPORT QgsProviderRegistry
{
  public:
    // TODO QGIS 5 - either move to QgsAbstractDataSourceWidget or remove altogether

    enum WidgetMode
    {

      Standalone,

      Embedded,

      Manager,
    };

    static QgsProviderRegistry *instance( const QString &pluginPath = QString() ) SIP_DISALLOWNONE;
 
    ~QgsProviderRegistry();

    Q_DECL_DEPRECATED QString library( const QString &providerKey ) const SIP_DEPRECATED;

    QString pluginList( bool asHtml = false ) const;

    QDir libraryDirectory() const;

    void setLibraryDirectory( const QDir &path );
 
    /*
     * IMPORTANT: While it seems like /Factory/ would be the correct annotation here, that's not
     * the case.
     * Paraphrasing Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
     *
     * "
     * /Factory/ is used when the instance returned is guaranteed to be new to Python.
     * In this case it isn't because it has already been seen when being returned by by the python function
     * creating the provider subclass.
     *
     * (However for a different sub-class implemented in C++ then it would be the first time it was seen
     * by Python so the /Factory/ on create() would be correct.)
     *
     * You might try using /TransferBack/ on createProvider() instead - that might be the best compromise.
     * "
     */

    QgsDataProvider *createProvider(
      const QString &providerKey,
      const QString &dataSource,
      const QgsDataProvider::ProviderOptions &options = QgsDataProvider::ProviderOptions(),
      Qgis::DataProviderReadFlags flags = Qgis::DataProviderReadFlags()
    ) SIP_TRANSFERBACK;

    Q_DECL_DEPRECATED Qgis::DataItemProviderCapabilities providerCapabilities( const QString &providerKey ) const SIP_DEPRECATED;

    QgsEmptyLayerCreationResult createEmptyLayer(
      const QString &providerKey,
      const QString &uri,
      const QgsFields &fields,
      Qgis::WkbType wkbType = Qgis::WkbType::NoGeometry,
      const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem(),
      Qgis::CreateLayerActionOnExisting actionOnExisting = Qgis::CreateLayerActionOnExisting::Abort
    );

    SIP_SKIP Qgis::VectorExportResult createEmptyLayer(
      const QString &providerKey,
      const QString &uri,
      const QgsFields &fields,
      Qgis::WkbType wkbType,
      const QgsCoordinateReferenceSystem &srs,
      bool overwrite,
      QMap<int, int> &oldToNewAttrIdxMap,
      QString &errorMessage,
      const QMap<QString, QVariant> *options,
      QString &createdLayerName
    );
 
    // TODO QGIS 5.0: rename createOptions to creationOptions for consistency with GDAL

    QgsRasterDataProvider *createRasterDataProvider(
      const QString &providerKey,
      const QString &uri,
      const QString &format,
      int nBands,
      Qgis::DataType type,
      int width,
      int height,
      double *geoTransform,
      const QgsCoordinateReferenceSystem &crs,
      const QStringList &createOptions = QStringList()
    ) SIP_FACTORY;

    QList<QPair<QString, QString> > pyramidResamplingMethods( const QString &providerKey );

    QVariantMap decodeUri( const QString &providerKey, const QString &uri );

    QString encodeUri( const QString &providerKey, const QVariantMap &parts );

    QString absoluteToRelativeUri( const QString &providerKey, const QString &uri, const QgsReadWriteContext &context ) const;

    QString relativeToAbsoluteUri( const QString &providerKey, const QString &uri, const QgsReadWriteContext &context ) const;

    Q_DECL_DEPRECATED QWidget *createSelectionWidget(
      const QString &providerKey, QWidget *parent = nullptr, Qt::WindowFlags fl = Qt::WindowFlags(), QgsProviderRegistry::WidgetMode widgetMode = QgsProviderRegistry::WidgetMode::Standalone
    ) SIP_DEPRECATED;

    QList< QgsDataItemProvider * > dataItemProviders( const QString &providerKey ) const SIP_FACTORY;

    int listStyles( const QString &providerKey, const QString &uri, QStringList &ids, QStringList &names, QStringList &descriptions, QString &errCause );

    bool styleExists( const QString &providerKey, const QString &uri, const QString &styleId, QString &errorCause SIP_OUT );

    QString getStyleById( const QString &providerKey, const QString &uri, const QString &styleId, QString &errCause );

    bool deleteStyleById( const QString &providerKey, const QString &uri, const QString &styleId, QString &errCause );

    bool saveStyle(
      const QString &providerKey,
      const QString &uri,
      const QString &qmlStyle,
      const QString &sldStyle,
      const QString &styleName,
      const QString &styleDescription,
      const QString &uiFileContent,
      bool useAsDefault,
      QString &errCause
    );

    QString loadStyle( const QString &providerKey, const QString &uri, QString &errCause );

    QString loadStoredStyle( const QString &providerKey, const QString &uri, QString &styleName, QString &errCause );

    bool saveLayerMetadata( const QString &providerKey, const QString &uri, const QgsLayerMetadata &metadata, QString &errorMessage SIP_OUT ) SIP_THROW( QgsNotSupportedException );

    bool createDb( const QString &providerKey, const QString &dbPath, QString &errCause );

    QgsTransaction *createTransaction( const QString &providerKey, const QString &connString ) SIP_FACTORY;

    Q_DECL_DEPRECATED QFunctionPointer function( const QString &providerKey, const QString &functionName ) const SIP_DEPRECATED;

    Q_DECL_DEPRECATED QLibrary *createProviderLibrary( const QString &providerKey ) const SIP_FACTORY SIP_DEPRECATED;

    QStringList providerList() const;

    QgsProviderMetadata *providerMetadata( const QString &providerKey ) const;

    QSet< QString > providersForLayerType( Qgis::LayerType type ) const;

    class CORE_EXPORT ProviderCandidateDetails
    {
      public:
        ProviderCandidateDetails( QgsProviderMetadata *metadata, const QList< Qgis::LayerType > &layerTypes )
          : mMetadata( metadata )
          , mLayerTypes( layerTypes )
        {}

        QgsProviderMetadata *metadata() const { return mMetadata; }

        QList<Qgis::LayerType> layerTypes() const { return mLayerTypes; }
 
#ifdef SIP_RUN
        // clang-format off
        SIP_PYOBJECT __repr__();
        % MethodCode
        QString str = u"<QgsProviderRegistry.ProviderCandidateDetails: %1>"_s.arg( sipCpp->metadata()->key() );
        sipRes = PyUnicode_FromString( str.toUtf8().constData() );
        % End
// clang-format on
#endif
 
        // clang-format off
        private:
        // clang-format on
        QgsProviderMetadata *mMetadata
        = nullptr;
 
        QList< Qgis::LayerType > mLayerTypes;
    };

    QList< QgsProviderRegistry::ProviderCandidateDetails > preferredProvidersForUri( const QString &uri ) const;

    class CORE_EXPORT UnusableUriDetails
    {
      public:
        UnusableUriDetails( const QString &uri = QString(), const QString &warning = QString(), const QList< Qgis::LayerType > &layerTypes = QList< Qgis::LayerType >() )
          : uri( uri )
          , warning( warning )
          , layerTypes( layerTypes )
        {}

        QString uri;

        QString warning;

        QString detailedWarning;

        QList<Qgis::LayerType> layerTypes;
 
#ifdef SIP_RUN
        // clang-format off
        SIP_PYOBJECT __repr__();
        % MethodCode
        QString str = u"<QgsProviderRegistry.UnusableUriDetails: %1>"_s.arg( sipCpp->warning );
        sipRes = PyUnicode_FromString( str.toUtf8().constData() );
        % End
// clang-format on
#endif
    };

    class CORE_EXPORT UnusableUriHandlerInterface
    {
      public:
        virtual ~UnusableUriHandlerInterface() = default;

        virtual bool matchesUri( const QString &uri ) const = 0;

        virtual UnusableUriDetails details( const QString &uri ) const = 0;
    };

    bool registerUnusableUriHandler( UnusableUriHandlerInterface *handler SIP_TRANSFER );

    bool handleUnusableUri( const QString &uri, UnusableUriDetails &details SIP_OUT ) const;

    bool shouldDeferUriForOtherProviders( const QString &uri, const QString &providerKey ) const;

    bool uriIsBlocklisted( const QString &uri ) const;

    QList< QgsProviderSublayerDetails > querySublayers( const QString &uri, Qgis::SublayerQueryFlags flags = Qgis::SublayerQueryFlags(), QgsFeedback *feedback = nullptr ) const;

    QString fileVectorFilters() const;

    QString fileRasterFilters() const;

    QString fileMeshFilters() const;

    QString fileMeshDatasetFilters() const;

    QString filePointCloudFilters() const;

    QString fileVectorTileFilters() const;

    QString fileTiledSceneFilters() const;

    QString databaseDrivers() const;
    QString directoryDrivers() const;
    QString protocolDrivers() const;

    Q_DECL_DEPRECATED void registerGuis( QWidget *widget ) SIP_DEPRECATED;

    bool registerProvider( QgsProviderMetadata *providerMetadata SIP_TRANSFER );

    SIP_SKIP typedef std::map<QString, QgsProviderMetadata *> Providers;
 
  private:
    QgsProviderRegistry( const QString &pluginPath );
 
#ifdef SIP_RUN
    QgsProviderRegistry( const QString &pluginPath );
#endif
 
    void init();
    void clean();

    Providers mProviders;

    QDir mLibraryDirectory;
 
    void rebuildFilterStrings();

    QString mVectorFileFilters;

    QString mRasterFileFilters;

    QString mMeshFileFilters;

    QString mMeshDatasetFileFilters;

    QString mPointCloudFileFilters;

    QString mVectorTileFileFilters;

    QString mTiledSceneFileFilters;

    QString mDatabaseDrivers;

    QString mDirectoryDrivers;

    QString mProtocolDrivers;
 
    QList< UnusableUriHandlerInterface * > mUnusableUriHandlers;

    static bool exists();
 
    friend class QgsApplication;
 
}; // class QgsProviderRegistry
 
#endif //QGSPROVIDERREGISTRY_H