qgsprovidermetadata.h

Go to the documentation of this file.

/***************************************************************************
                    qgsprovidermetadata.h  -  Metadata class for
                    describing a data provider.
                             -------------------
    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 QGSPROVIDERMETADATA_H
#define QGSPROVIDERMETADATA_H
 
 
#include <functional>
#include <memory>
 
#include "qgis_core.h"
#include "qgis_sip.h"
#include "qgsabstractproviderconnection.h"
#include "qgsdataprovider.h"
#include "qgsfields.h"
 
#include <QList>
#include <QMap>
#include <QPair>
#include <QString>
#include <QVariantMap>
 
using namespace Qt::StringLiterals;
 
class QgsDataItem;
class QgsDataItemProvider;
class QgsTransaction;
 
class QgsRasterDataProvider;
class QgsMeshDataProvider;
class QgsAbstractDatabaseProviderConnection;
class QgsLayerMetadata;
class QgsProviderSublayerDetails;
class QgsFeedback;
 
struct QgsMesh;

class CORE_EXPORT QgsMeshDriverMetadata
{
    Q_GADGET
 
  public:
    enum MeshDriverCapability SIP_ENUM_BASETYPE( IntFlag )
    {
      CanWriteFaceDatasets = 1 << 0,   
      CanWriteVertexDatasets = 1 << 1, 
      CanWriteEdgeDatasets = 1 << 2,   
      CanWriteMeshData = 1 << 3,       
    };
 
    Q_ENUM( MeshDriverCapability )
    Q_DECLARE_FLAGS( MeshDriverCapabilities, MeshDriverCapability )
    Q_FLAG( MeshDriverCapabilities )

    QgsMeshDriverMetadata();

    Q_DECL_DEPRECATED QgsMeshDriverMetadata( const QString &name, const QString &description, const MeshDriverCapabilities &capabilities, const QString &writeDatasetOnFileSuffix ) SIP_DEPRECATED;

    QgsMeshDriverMetadata(
      const QString &name, const QString &description, const MeshDriverCapabilities &capabilities, const QString &writeDatasetOnFileSuffix, const QString &writeMeshFrameOnFileSuffix, int maxVerticesPerface
    );

    MeshDriverCapabilities capabilities() const;

    QString name() const;

    QString description() const;

    QString writeDatasetOnFileSuffix() const;

    QString writeMeshFrameOnFileSuffix() const;

    int maximumVerticesCountPerFace() const;
 
  private:
    QString mName;
    QString mDescription;
    MeshDriverCapabilities mCapabilities;
    QString mWriteDatasetOnFileSuffix;
    QString mWriteMeshFrameOnFileSuffix;
    int mMaxVerticesPerFace = -1;
};
 
Q_DECLARE_OPERATORS_FOR_FLAGS( QgsMeshDriverMetadata::MeshDriverCapabilities )
 

class CORE_EXPORT QgsEmptyLayerCreationResult
{
  public:
    QgsEmptyLayerCreationResult() = default;
 
#ifndef SIP_RUN
    QgsEmptyLayerCreationResult( Qgis::VectorExportResult result, const QString &createdLayerUri, const QString &errorMessage, const QMap<int, int> &createdAttributeIndexMap )
      : mResult( result )
      , mCreatedLayerUri( createdLayerUri )
      , mErrorMessage( errorMessage )
      , mCreatedAttributeIndexMap( createdAttributeIndexMap )
    {}
#endif

    Qgis::VectorExportResult result() const { return mResult; }

    QString createdLayerUri() const { return mCreatedLayerUri; }

    QString errorMessage() const { return mErrorMessage; }

    QMap<int, int> createdAttributeIndexMap() const { return mCreatedAttributeIndexMap; }
 
  private:
    Qgis::VectorExportResult mResult = Qgis::VectorExportResult::UserCanceled;
    QString mCreatedLayerUri;
    QString mErrorMessage;
    QMap<int, int> mCreatedAttributeIndexMap;
};

class CORE_EXPORT QgsProviderMetadata : public QObject
{
    Q_OBJECT
 
  public:
    enum ProviderMetadataCapability SIP_ENUM_BASETYPE( IntFlag )
    {
      PriorityForUri = 1 << 0,   
      LayerTypesForUri = 1 << 1, 
      QuerySublayers = 1 << 2,   
      CreateDatabase = 1 << 3,   
      UrisReferToSame = 1 << 4,  
    };
    Q_DECLARE_FLAGS( ProviderMetadataCapabilities, ProviderMetadataCapability )
 
    
    enum ProviderCapability SIP_ENUM_BASETYPE( IntFlag )
    {
      FileBasedUris = 1 << 0,          
      SaveLayerMetadata = 1 << 1,      
      ParallelCreateProvider = 1 << 2, 
    };
    Q_DECLARE_FLAGS( ProviderCapabilities, ProviderCapability )
 
    
    SIP_SKIP typedef std::function< QgsDataProvider *( const QString &, const QgsDataProvider::ProviderOptions &, Qgis::DataProviderReadFlags & ) > CreateDataProviderFunction;

    QgsProviderMetadata( const QString &key, const QString &description, const QString &library = QString() );

    SIP_SKIP Q_DECL_DEPRECATED QgsProviderMetadata( const QString &key, const QString &description, const QgsProviderMetadata::CreateDataProviderFunction &createFunc );
 
    ~QgsProviderMetadata() override;

    QString key() const;

    QString description() const;

    virtual QIcon icon() const;

    virtual QgsProviderMetadata::ProviderMetadataCapabilities capabilities() const;

    virtual QgsProviderMetadata::ProviderCapabilities providerCapabilities() const;

#ifndef SIP_RUN
    virtual QList< Qgis::LayerType > supportedLayerTypes() const;
#else
    // clang-format off
    SIP_PYOBJECT supportedLayerTypes() const SIP_TYPEHINT( List[Qgis.LayerType] );
    % MethodCode
    // adapted from the qpymultimedia_qlist.sip file from the PyQt6 sources
 
    const QList< Qgis::LayerType > cppRes = sipCpp->supportedLayerTypes();
 
    PyObject *l = PyList_New( cppRes.size() );
 
    if ( !l )
      sipIsErr = 1;
    else
    {
      for ( int i = 0; i < cppRes.size(); ++i )
      {
        PyObject *eobj = sipConvertFromEnum( static_cast<int>( cppRes.at( i ) ),
                                             sipType_Qgis_LayerType );
 
        if ( !eobj )
        {
          sipIsErr = 1;
        }
 
        PyList_SetItem( l, i, eobj );
      }
 
      if ( !sipIsErr )
      {
        sipRes = l;
      }
      else
      {
        Py_DECREF( l );
      }
    }
    % End
// clang-format on
#endif

    Q_DECL_DEPRECATED QString library() const SIP_DEPRECATED;

    SIP_SKIP Q_DECL_DEPRECATED CreateDataProviderFunction createFunction() const;

    virtual void initProvider();

    virtual void cleanupProvider();

    virtual QString filters( Qgis::FileFilterType type );

    virtual QList<QgsMeshDriverMetadata> meshDriversMetadata();

    virtual int priorityForUri( const QString &uri ) const;

    virtual QList< Qgis::LayerType > validLayerTypesForUri( const QString &uri ) const;

    virtual bool uriIsBlocklisted( const QString &uri ) const;

    virtual QStringList sidecarFilesForUri( const QString &uri ) const;

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

    virtual QString suggestGroupNameForUri( const QString &uri ) const;

    virtual QgsDataProvider *createProvider( const QString &uri, const QgsDataProvider::ProviderOptions &options, Qgis::DataProviderReadFlags flags = Qgis::DataProviderReadFlags() ) SIP_FACTORY;

    static void setBoolParameter( QVariantMap &uri, const QString &parameter, const QVariant &value );

    static bool boolParameter( const QVariantMap &uri, const QString &parameter, bool defaultValue = false );

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

    virtual Qgis::VectorExportResult createEmptyLayer(
      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 &createdLayerUri
    );
#endif

    virtual bool createDatabase( const QString &uri, QString &errorMessage SIP_OUT );
 
    // TODO QGIS 5.0: rename createOptions to creationOptions for consistency with GDAL

    virtual QgsRasterDataProvider *createRasterDataProvider(
      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;

    virtual bool createMeshData(
      const QgsMesh &mesh, const QString &fileName, const QString &driverName, const QgsCoordinateReferenceSystem &crs, const QMap<QString, QString> &metadata = QMap<QString, QString>()
    ) const;

    virtual bool createMeshData( const QgsMesh &mesh, const QString &uri, const QgsCoordinateReferenceSystem &crs, const QMap<QString, QString> &metadata = QMap<QString, QString>() ) const;

    virtual QList<QPair<QString, QString> > pyramidResamplingMethods();

    virtual QVariantMap decodeUri( const QString &uri ) const;

    virtual QString encodeUri( const QVariantMap &parts ) const;

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

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

    virtual QString cleanUri( const QString &uri, Qgis::UriCleaningFlags flags = Qgis::UriCleaningFlag::RemoveCredentials ) const;

    virtual bool urisReferToSame( const QString &uri1, const QString &uri2, Qgis::SourceHierarchyLevel level = Qgis::SourceHierarchyLevel::Object ) const;

    virtual QList< QgsDataItemProvider * > dataItemProviders() const SIP_FACTORY;

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

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

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

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

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

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

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

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

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

    virtual QgsTransaction *createTransaction( const QString &connString ) SIP_FACTORY;

    virtual QMap<QString, QgsAbstractProviderConnection *> connections( bool cached = true ) SIP_THROW( QgsProviderConnectionException );

    QMap<QString, QgsAbstractDatabaseProviderConnection *> dbConnections( bool cached = true ) SIP_THROW( QgsProviderConnectionException );

    QgsAbstractProviderConnection *findConnection( const QString &name, bool cached = true ) SIP_THROW( QgsProviderConnectionException );
 
#ifndef SIP_RUN

    template<typename T> QMap<QString, T *> connections( bool cached = true );
 
 
#endif

    virtual QgsAbstractProviderConnection *createConnection( const QString &uri, const QVariantMap &configuration ) SIP_THROW( QgsProviderConnectionException ) SIP_FACTORY;

    virtual QgsAbstractProviderConnection *createConnection( const QString &name ) SIP_THROW( QgsProviderConnectionException ) SIP_FACTORY;

    virtual void deleteConnection( const QString &name ) SIP_THROW( QgsProviderConnectionException );

    virtual void saveConnection( const QgsAbstractProviderConnection *connection, const QString &name ) SIP_THROW( QgsProviderConnectionException );
 
#ifdef SIP_RUN
    // clang-format off
    SIP_PYOBJECT __repr__();
    % MethodCode
    QString str = u"<QgsProviderMetadata: %1>"_s.arg( sipCpp->key() );
    sipRes = PyUnicode_FromString( str.toUtf8().constData() );
    % End
// clang-format on
#endif
 
        signals :

      void connectionCreated( const QString &name );

    void connectionDeleted( const QString &name );

    void connectionChanged( const QString &name );
 
  protected:
#ifndef SIP_RUN
 
    // Common functionality for connections management, to be moved into the class
    // when all the providers are ready
    // T_provider_conn: subclass of QgsAbstractProviderConnection,
    // T_conn: provider connection class (such as QgsOgrDbConnection or QgsPostgresConn)
    // TODO QGIS 5: remove all old provider conn classes and move functionality into QgsAbstractProviderConnection subclasses
    template<class T_provider_conn, class T_conn> QMap<QString, QgsAbstractProviderConnection *> connectionsProtected( bool cached = true )
    {
      if ( !cached || mProviderConnections.isEmpty() )
      {
        qDeleteAll( mProviderConnections );
        mProviderConnections.clear();
        const auto connNames { T_conn::connectionList() };
        for ( const auto &cname : connNames )
        {
          mProviderConnections.insert( cname, new T_provider_conn( cname ) );
        }
      }
      return mProviderConnections;
    }
 
    template<class T_provider_conn> void deleteConnectionProtected( const QString &name )
    {
      T_provider_conn conn( name );
      conn.remove( name );
      mProviderConnections.clear();
      emit connectionDeleted( name );
    }
    virtual void saveConnectionProtected( const QgsAbstractProviderConnection *connection, const QString &name );
    QMap<QString, QgsAbstractProviderConnection *> mProviderConnections;

 
#endif
 
  private:
    QString mKey;

    QString mDescription;

    QString mLibrary;
 
    CreateDataProviderFunction mCreateFunction = nullptr;
};
 
Q_DECLARE_OPERATORS_FOR_FLAGS( QgsProviderMetadata::ProviderMetadataCapabilities )
Q_DECLARE_OPERATORS_FOR_FLAGS( QgsProviderMetadata::ProviderCapabilities )
 
#endif //QGSPROVIDERMETADATA_H