QGIS API Documentation  3.27.0-Master (e113457133)
qgsproviderregistry.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgsproviderregistry.h - Singleton class for
3  registering data providers.
4  -------------------
5  begin : Sat Jan 10 2004
6  copyright : (C) 2004 by Gary E.Sherman
7  email : sherman at mrcc.com
8  ***************************************************************************/
9 
10 /***************************************************************************
11  * *
12  * This program is free software; you can redistribute it and/or modify *
13  * it under the terms of the GNU General Public License as published by *
14  * the Free Software Foundation; either version 2 of the License, or *
15  * (at your option) any later version. *
16  * *
17  ***************************************************************************/
18 
19 #ifndef QGSPROVIDERREGISTRY_H
20 #define QGSPROVIDERREGISTRY_H
21 
22 #include <map>
23 
24 #include <QDir>
25 #include <QLibrary>
26 #include <QString>
27 
28 #include "qgsdataprovider.h"
29 #include "qgis_core.h"
30 #include "qgis_sip.h"
31 
32 #include <vector>
33 #include <memory>
34 
36 class QgsVectorLayer;
39 class QgsDataItem;
41 class QgsTransaction;
42 class QgsFields;
44 class QgsFeedback;
45 
60 class CORE_EXPORT QgsProviderRegistry
61 {
62 
63  public:
64 
65  // TODO QGIS 4 - either move to QgsAbstractDataSourceWidget or remove altogether
66 
71  {
72 
79 
85 
92  };
93 
95  static QgsProviderRegistry *instance( const QString &pluginPath = QString() );
96 
98 
107  Q_DECL_DEPRECATED QString library( const QString &providerKey ) const SIP_DEPRECATED;
108 
110  QString pluginList( bool asHtml = false ) const;
111 
115  QDir libraryDirectory() const;
116 
118  void setLibraryDirectory( const QDir &path );
119 
120  /*
121  * IMPORTANT: While it seems like /Factory/ would be the correct annotation here, that's not
122  * the case.
123  * Paraphrasing Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
124  *
125  * "
126  * /Factory/ is used when the instance returned is guaranteed to be new to Python.
127  * In this case it isn't because it has already been seen when being returned by by the python function
128  * creating the provider subclass.
129  *
130  * (However for a different sub-class implemented in C++ then it would be the first time it was seen
131  * by Python so the /Factory/ on create() would be correct.)
132  *
133  * You might try using /TransferBack/ on createProvider() instead - that might be the best compromise.
134  * "
135  */
136 
147  QgsDataProvider *createProvider( const QString &providerKey,
148  const QString &dataSource,
150  QgsDataProvider::ReadFlags flags = QgsDataProvider::ReadFlags() ) SIP_TRANSFERBACK;
151 
158  Q_DECL_DEPRECATED int providerCapabilities( const QString &providerKey ) const SIP_DEPRECATED;
159 
165  SIP_SKIP Qgis::VectorExportResult createEmptyLayer( const QString &providerKey, const QString &uri, const QgsFields &fields, QgsWkbTypes::Type wkbType, const QgsCoordinateReferenceSystem &srs, bool overwrite, QMap<int, int> &oldToNewAttrIdxMap, QString &errorMessage, const QMap<QString, QVariant> *options );
166 
173  QgsRasterDataProvider *createRasterDataProvider(
174  const QString &providerKey,
175  const QString &uri,
176  const QString &format,
177  int nBands,
178  Qgis::DataType type,
179  int width, int height,
180  double *geoTransform,
182  const QStringList &createOptions = QStringList() ) SIP_FACTORY;
183 
189  QList<QPair<QString, QString> > pyramidResamplingMethods( const QString &providerKey );
190 
199  QVariantMap decodeUri( const QString &providerKey, const QString &uri );
200 
210  QString encodeUri( const QString &providerKey, const QVariantMap &parts );
211 
218  Q_DECL_DEPRECATED QWidget *createSelectionWidget( const QString &providerKey, QWidget *parent = nullptr, Qt::WindowFlags fl = Qt::WindowFlags(), QgsProviderRegistry::WidgetMode widgetMode = QgsProviderRegistry::WidgetMode::None ) SIP_DEPRECATED;
219 
225  QList< QgsDataItemProvider * > dataItemProviders( const QString &providerKey ) const SIP_FACTORY;
226 
232  int listStyles( const QString &providerKey,
233  const QString &uri,
234  QStringList &ids,
235  QStringList &names,
236  QStringList &descriptions,
237  QString &errCause );
238 
251  bool styleExists( const QString &providerKey, const QString &uri, const QString &styleId, QString &errorCause SIP_OUT );
252 
260  QString getStyleById( const QString &providerKey, const QString &uri, const QString &styleId, QString &errCause );
261 
266  bool deleteStyleById( const QString &providerKey, const QString &uri, const QString &styleId, QString &errCause );
267 
273  bool saveStyle( const QString &providerKey, const QString &uri, const QString &qmlStyle, const QString &sldStyle,
274  const QString &styleName, const QString &styleDescription,
275  const QString &uiFileContent, bool useAsDefault, QString &errCause );
276 
281  QString loadStyle( const QString &providerKey, const QString &uri, QString &errCause );
282 
298  bool saveLayerMetadata( const QString &providerKey, const QString &uri, const QgsLayerMetadata &metadata, QString &errorMessage SIP_OUT ) SIP_THROW( QgsNotSupportedException );
299 
304  bool createDb( const QString &providerKey, const QString &dbPath, QString &errCause );
305 
310  QgsTransaction *createTransaction( const QString &providerKey, const QString &connString ) SIP_FACTORY;
311 
322  Q_DECL_DEPRECATED QFunctionPointer function( const QString &providerKey, const QString &functionName ) const SIP_DEPRECATED;
323 
333  Q_DECL_DEPRECATED QLibrary *createProviderLibrary( const QString &providerKey ) const SIP_FACTORY SIP_DEPRECATED;
334 
336  QStringList providerList() const;
337 
339  QgsProviderMetadata *providerMetadata( const QString &providerKey ) const;
340 
347  QSet< QString > providersForLayerType( QgsMapLayerType type ) const;
348 
356  class CORE_EXPORT ProviderCandidateDetails
357  {
358 
359  public:
360 
364  ProviderCandidateDetails( QgsProviderMetadata *metadata, const QList< QgsMapLayerType > &layerTypes )
365  : mMetadata( metadata )
366  , mLayerTypes( layerTypes )
367  {}
368 
372  QgsProviderMetadata *metadata() const { return mMetadata; }
373 
378  QList<QgsMapLayerType> layerTypes() const { return mLayerTypes; }
379 
380 #ifdef SIP_RUN
381  SIP_PYOBJECT __repr__();
382  % MethodCode
383  QString str = QStringLiteral( "<QgsProviderRegistry.ProviderCandidateDetails: %1>" ).arg( sipCpp->metadata()->key() );
384  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
385  % End
386 #endif
387 
388  private:
389  QgsProviderMetadata *mMetadata = nullptr;
390 
391  QList< QgsMapLayerType > mLayerTypes;
392 
393  };
394 
411  QList< QgsProviderRegistry::ProviderCandidateDetails > preferredProvidersForUri( const QString &uri ) const;
412 
424  class CORE_EXPORT UnusableUriDetails
425  {
426  public:
427 
434  UnusableUriDetails( const QString &uri = QString(), const QString &warning = QString(), const QList< QgsMapLayerType > &layerTypes = QList< QgsMapLayerType >() )
435  : uri( uri )
436  , warning( warning )
437  , layerTypes( layerTypes )
438  {}
439 
443  QString uri;
444 
448  QString warning;
449 
454 
459  QList<QgsMapLayerType> layerTypes;
460 
461 #ifdef SIP_RUN
462  SIP_PYOBJECT __repr__();
463  % MethodCode
464  QString str = QStringLiteral( "<QgsProviderRegistry.UnusableUriDetails: %1>" ).arg( sipCpp->warning );
465  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
466  % End
467 #endif
468 
469  };
470 
483  class CORE_EXPORT UnusableUriHandlerInterface
484  {
485 
486  public:
487 
488  virtual ~UnusableUriHandlerInterface() = default;
489 
493  virtual bool matchesUri( const QString &uri ) const = 0;
494 
498  virtual UnusableUriDetails details( const QString &uri ) const = 0;
499 
500  };
501 
512  bool registerUnusableUriHandler( UnusableUriHandlerInterface *handler SIP_TRANSFER );
513 
537  bool handleUnusableUri( const QString &uri, UnusableUriDetails &details SIP_OUT ) const;
538 
555  bool shouldDeferUriForOtherProviders( const QString &uri, const QString &providerKey ) const;
556 
570  bool uriIsBlocklisted( const QString &uri ) const;
571 
583  QList< QgsProviderSublayerDetails > querySublayers( const QString &uri, Qgis::SublayerQueryFlags flags = Qgis::SublayerQueryFlags(), QgsFeedback *feedback = nullptr ) const;
584 
595  QString fileVectorFilters() const;
596 
609  QString fileRasterFilters() const;
610 
624  QString fileMeshFilters() const;
625 
636  QString fileMeshDatasetFilters() const;
637 
650  QString filePointCloudFilters() const;
651 
653  QString databaseDrivers() const;
655  QString directoryDrivers() const;
657  QString protocolDrivers() const;
658 
662  Q_DECL_DEPRECATED void registerGuis( QWidget *widget ) SIP_DEPRECATED;
663 
670  bool registerProvider( QgsProviderMetadata *providerMetadata SIP_TRANSFER );
671 
673  SIP_SKIP typedef std::map<QString, QgsProviderMetadata *> Providers;
674 
675  private:
677  QgsProviderRegistry( const QString &pluginPath );
678 
679 #ifdef SIP_RUN
680  QgsProviderRegistry( const QString &pluginPath );
681 #endif
682 
683  void init();
684  void clean();
685 
687  Providers mProviders;
688 
690  QDir mLibraryDirectory;
691 
701  QString mVectorFileFilters;
702 
706  QString mRasterFileFilters;
707 
711  QString mMeshFileFilters;
712 
716  QString mMeshDatasetFileFilters;
717 
721  QString mPointCloudFileFilters;
722 
729  QString mDatabaseDrivers;
730 
736  QString mDirectoryDrivers;
737 
744  QString mProtocolDrivers;
745 
746  QList< UnusableUriHandlerInterface * > mUnusableUriHandlers;
747 
751  static bool exists();
752 
753  friend class QgsApplication;
754 
755 }; // class QgsProviderRegistry
756 
757 #endif //QGSPROVIDERREGISTRY_H
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:72
Extends QApplication to provide access to QGIS specific resources such as theme paths,...
This class represents a coordinate reference system (CRS).
This is the interface for those who want to add custom data items to the browser tree.
Base class for all items in the model.
Definition: qgsdataitem.h:46
Abstract base class for spatial data provider implementations.
Base class for feedback objects to be used for cancellation of something running in a worker thread.
Definition: qgsfeedback.h:45
Container of fields for a vector layer.
Definition: qgsfields.h:45
A structured metadata store for a map layer.
Custom exception class which is raised when an operation is not supported.
Definition: qgsexception.h:118
Holds data provider key, description, and associated shared library file or function pointer informat...
Contains information pertaining to a candidate provider.
QList< QgsMapLayerType > layerTypes() const
Returns a list of map layer types which are valid options for opening the target using this candidate...
ProviderCandidateDetails(QgsProviderMetadata *metadata, const QList< QgsMapLayerType > &layerTypes)
Constructor for ProviderCandidateDetails, with the specified provider metadata and valid candidate la...
QgsProviderMetadata * metadata() const
Returns the candidate provider metadata.
Contains information about unusable URIs which aren't handled by any registered providers.
QString warning
Contains a short, user-friendly, translated message advising why the URI is not usable.
UnusableUriDetails(const QString &uri=QString(), const QString &warning=QString(), const QList< QgsMapLayerType > &layerTypes=QList< QgsMapLayerType >())
Constructor for UnusableUriDetails for the given uri, with the specified user-friendly,...
QString uri
URI which could not be handled.
QString detailedWarning
Contains a longer, user-friendly, translated message advising why the URI is not usable.
QList< QgsMapLayerType > layerTypes
Contains a list of map layer types which are usually valid options for opening the target URI.
An interface used to handle unusable URIs which aren't handled by any registered providers,...
virtual UnusableUriDetails details(const QString &uri) const =0
Returns the details for advising the user why the uri is not usable.
virtual bool matchesUri(const QString &uri) const =0
Returns true if the handle is an unusable URI handler for the specified uri.
A registry / canonical manager of data providers.
std::map< QString, QgsProviderMetadata * > Providers
Type for data provider metadata associative container.
WidgetMode
Different ways a source select dialog can be used.
@ Embedded
Used for the data source manager dialog where the widget is embedded as the main content for a partic...
@ None
Basic mode when the widget is used as a standalone dialog.
@ Manager
Used by data items for QgsDataItem::paramWidget().
Contains details about a sub layer available from a dataset.
Base class for raster data providers.
This class allows including a set of layers in a database-side transaction, provided the layer data p...
Represents a vector layer which manages a vector based data sets.
Handles storage of information regarding WKB types and their properties.
Definition: qgswkbtypes.h:42
QgsMapLayerType
Types of layers that can be added to a map.
Definition: qgis.h:47
#define str(x)
Definition: qgis.cpp:37
#define SIP_THROW(name)
Definition: qgis_sip.h:198
#define SIP_DEPRECATED
Definition: qgis_sip.h:106
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_TRANSFER
Definition: qgis_sip.h:36
#define SIP_OUT
Definition: qgis_sip.h:58
#define SIP_TRANSFERBACK
Definition: qgis_sip.h:48
#define SIP_FACTORY
Definition: qgis_sip.h:76
const QgsCoordinateReferenceSystem & crs
Setting options for creating vector data providers.