QGIS API Documentation  3.21.0-Master (2d5a580dfc)
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 
244  QString getStyleById( const QString &providerKey, const QString &uri, QString styleId, QString &errCause );
245 
250  bool deleteStyleById( const QString &providerKey, const QString &uri, QString styleId, QString &errCause );
251 
257  bool saveStyle( const QString &providerKey, const QString &uri, const QString &qmlStyle, const QString &sldStyle,
258  const QString &styleName, const QString &styleDescription,
259  const QString &uiFileContent, bool useAsDefault, QString &errCause );
260 
265  QString loadStyle( const QString &providerKey, const QString &uri, QString &errCause );
266 
282  bool saveLayerMetadata( const QString &providerKey, const QString &uri, const QgsLayerMetadata &metadata, QString &errorMessage SIP_OUT ) SIP_THROW( QgsNotSupportedException );
283 
288  bool createDb( const QString &providerKey, const QString &dbPath, QString &errCause );
289 
294  QgsTransaction *createTransaction( const QString &providerKey, const QString &connString ) SIP_FACTORY;
295 
306  Q_DECL_DEPRECATED QFunctionPointer function( const QString &providerKey, const QString &functionName ) SIP_DEPRECATED;
307 
317  Q_DECL_DEPRECATED QLibrary *createProviderLibrary( const QString &providerKey ) const SIP_FACTORY SIP_DEPRECATED;
318 
320  QStringList providerList() const;
321 
323  QgsProviderMetadata *providerMetadata( const QString &providerKey ) const;
324 
332  class CORE_EXPORT ProviderCandidateDetails
333  {
334 
335  public:
336 
340  ProviderCandidateDetails( QgsProviderMetadata *metadata, const QList< QgsMapLayerType > &layerTypes )
341  : mMetadata( metadata )
342  , mLayerTypes( layerTypes )
343  {}
344 
348  QgsProviderMetadata *metadata() const { return mMetadata; }
349 
354  QList<QgsMapLayerType> layerTypes() const { return mLayerTypes; }
355 
356 #ifdef SIP_RUN
357  SIP_PYOBJECT __repr__();
358  % MethodCode
359  QString str = QStringLiteral( "<QgsProviderRegistry.ProviderCandidateDetails: %1>" ).arg( sipCpp->metadata()->key() );
360  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
361  % End
362 #endif
363 
364  private:
365  QgsProviderMetadata *mMetadata = nullptr;
366 
367  QList< QgsMapLayerType > mLayerTypes;
368 
369  };
370 
387  QList< QgsProviderRegistry::ProviderCandidateDetails > preferredProvidersForUri( const QString &uri ) const;
388 
400  class CORE_EXPORT UnusableUriDetails
401  {
402  public:
403 
410  UnusableUriDetails( const QString &uri = QString(), const QString &warning = QString(), const QList< QgsMapLayerType > &layerTypes = QList< QgsMapLayerType >() )
411  : uri( uri )
412  , warning( warning )
413  , layerTypes( layerTypes )
414  {}
415 
419  QString uri;
420 
424  QString warning;
425 
430 
435  QList<QgsMapLayerType> layerTypes;
436 
437 #ifdef SIP_RUN
438  SIP_PYOBJECT __repr__();
439  % MethodCode
440  QString str = QStringLiteral( "<QgsProviderRegistry.UnusableUriDetails: %1>" ).arg( sipCpp->warning );
441  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
442  % End
443 #endif
444 
445  };
446 
459  class CORE_EXPORT UnusableUriHandlerInterface
460  {
461 
462  public:
463 
464  virtual ~UnusableUriHandlerInterface() = default;
465 
469  virtual bool matchesUri( const QString &uri ) const = 0;
470 
474  virtual UnusableUriDetails details( const QString &uri ) const = 0;
475 
476  };
477 
488  bool registerUnusableUriHandler( UnusableUriHandlerInterface *handler SIP_TRANSFER );
489 
513  bool handleUnusableUri( const QString &uri, UnusableUriDetails &details SIP_OUT ) const;
514 
531  bool shouldDeferUriForOtherProviders( const QString &uri, const QString &providerKey ) const;
532 
546  bool uriIsBlocklisted( const QString &uri ) const;
547 
559  QList< QgsProviderSublayerDetails > querySublayers( const QString &uri, Qgis::SublayerQueryFlags flags = Qgis::SublayerQueryFlags(), QgsFeedback *feedback = nullptr ) const;
560 
571  QString fileVectorFilters() const;
572 
585  QString fileRasterFilters() const;
586 
600  QString fileMeshFilters() const;
601 
612  QString fileMeshDatasetFilters() const;
613 
626  QString filePointCloudFilters() const;
627 
629  QString databaseDrivers() const;
631  QString directoryDrivers() const;
633  QString protocolDrivers() const;
634 
638  Q_DECL_DEPRECATED void registerGuis( QWidget *widget ) SIP_DEPRECATED;
639 
646  bool registerProvider( QgsProviderMetadata *providerMetadata SIP_TRANSFER );
647 
649  SIP_SKIP typedef std::map<QString, QgsProviderMetadata *> Providers;
650 
651  private:
653  QgsProviderRegistry( const QString &pluginPath );
654 
655 #ifdef SIP_RUN
656  QgsProviderRegistry( const QString &pluginPath );
657 #endif
658 
659  void init();
660  void clean();
661 
663  Providers mProviders;
664 
666  QDir mLibraryDirectory;
667 
677  QString mVectorFileFilters;
678 
682  QString mRasterFileFilters;
683 
687  QString mMeshFileFilters;
688 
692  QString mMeshDatasetFileFilters;
693 
697  QString mPointCloudFileFilters;
698 
705  QString mDatabaseDrivers;
706 
712  QString mDirectoryDrivers;
713 
720  QString mProtocolDrivers;
721 
722  QList< UnusableUriHandlerInterface * > mUnusableUriHandlers;
723 
727  static bool exists();
728 
729  friend class QgsApplication;
730 
731 }; // class QgsProviderRegistry
732 
733 #endif //QGSPROVIDERREGISTRY_H
734 
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:63
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
#define str(x)
Definition: qgis.cpp:37
#define SIP_THROW(name)
Definition: qgis_sip.h:189
#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.