QGIS API Documentation  3.21.0-Master (564c892cfd)
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;
43 
58 class CORE_EXPORT QgsProviderRegistry
59 {
60 
61  public:
62 
63  // TODO QGIS 4 - either move to QgsAbstractDataSourceWidget or remove altogether
64 
69  {
70 
77 
83 
90  };
91 
93  static QgsProviderRegistry *instance( const QString &pluginPath = QString() );
94 
96 
105  Q_DECL_DEPRECATED QString library( const QString &providerKey ) const SIP_DEPRECATED;
106 
108  QString pluginList( bool asHtml = false ) const;
109 
113  QDir libraryDirectory() const;
114 
116  void setLibraryDirectory( const QDir &path );
117 
118  /*
119  * IMPORTANT: While it seems like /Factory/ would be the correct annotation here, that's not
120  * the case.
121  * Paraphrasing Phil Thomson's advice on https://www.riverbankcomputing.com/pipermail/pyqt/2017-July/039450.html:
122  *
123  * "
124  * /Factory/ is used when the instance returned is guaranteed to be new to Python.
125  * In this case it isn't because it has already been seen when being returned by by the python function
126  * creating the provider subclass.
127  *
128  * (However for a different sub-class implemented in C++ then it would be the first time it was seen
129  * by Python so the /Factory/ on create() would be correct.)
130  *
131  * You might try using /TransferBack/ on createProvider() instead - that might be the best compromise.
132  * "
133  */
134 
145  QgsDataProvider *createProvider( const QString &providerKey,
146  const QString &dataSource,
148  QgsDataProvider::ReadFlags flags = QgsDataProvider::ReadFlags() ) SIP_TRANSFERBACK;
149 
156  Q_DECL_DEPRECATED int providerCapabilities( const QString &providerKey ) const SIP_DEPRECATED;
157 
163  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 );
164 
171  QgsRasterDataProvider *createRasterDataProvider(
172  const QString &providerKey,
173  const QString &uri,
174  const QString &format,
175  int nBands,
176  Qgis::DataType type,
177  int width, int height,
178  double *geoTransform,
180  const QStringList &createOptions = QStringList() ) SIP_FACTORY;
181 
187  QList<QPair<QString, QString> > pyramidResamplingMethods( const QString &providerKey );
188 
197  QVariantMap decodeUri( const QString &providerKey, const QString &uri );
198 
208  QString encodeUri( const QString &providerKey, const QVariantMap &parts );
209 
216  Q_DECL_DEPRECATED QWidget *createSelectionWidget( const QString &providerKey, QWidget *parent = nullptr, Qt::WindowFlags fl = Qt::WindowFlags(), QgsProviderRegistry::WidgetMode widgetMode = QgsProviderRegistry::WidgetMode::None ) SIP_DEPRECATED;
217 
223  QList< QgsDataItemProvider * > dataItemProviders( const QString &providerKey ) const SIP_FACTORY;
224 
230  int listStyles( const QString &providerKey,
231  const QString &uri,
232  QStringList &ids,
233  QStringList &names,
234  QStringList &descriptions,
235  QString &errCause );
236 
242  QString getStyleById( const QString &providerKey, const QString &uri, QString styleId, QString &errCause );
243 
248  bool deleteStyleById( const QString &providerKey, const QString &uri, QString styleId, QString &errCause );
249 
255  bool saveStyle( const QString &providerKey, const QString &uri, const QString &qmlStyle, const QString &sldStyle,
256  const QString &styleName, const QString &styleDescription,
257  const QString &uiFileContent, bool useAsDefault, QString &errCause );
258 
263  QString loadStyle( const QString &providerKey, const QString &uri, QString &errCause );
264 
280  bool saveLayerMetadata( const QString &providerKey, const QString &uri, const QgsLayerMetadata &metadata, QString &errorMessage SIP_OUT ) SIP_THROW( QgsNotSupportedException );
281 
286  bool createDb( const QString &providerKey, const QString &dbPath, QString &errCause );
287 
292  QgsTransaction *createTransaction( const QString &providerKey, const QString &connString ) SIP_FACTORY;
293 
304  Q_DECL_DEPRECATED QFunctionPointer function( const QString &providerKey, const QString &functionName ) SIP_DEPRECATED;
305 
315  Q_DECL_DEPRECATED QLibrary *createProviderLibrary( const QString &providerKey ) const SIP_FACTORY SIP_DEPRECATED;
316 
318  QStringList providerList() const;
319 
321  QgsProviderMetadata *providerMetadata( const QString &providerKey ) const;
322 
330  class CORE_EXPORT ProviderCandidateDetails
331  {
332 
333  public:
334 
338  ProviderCandidateDetails( QgsProviderMetadata *metadata, const QList< QgsMapLayerType > &layerTypes )
339  : mMetadata( metadata )
340  , mLayerTypes( layerTypes )
341  {}
342 
346  QgsProviderMetadata *metadata() const { return mMetadata; }
347 
352  QList<QgsMapLayerType> layerTypes() const { return mLayerTypes; }
353 
354 #ifdef SIP_RUN
355  SIP_PYOBJECT __repr__();
356  % MethodCode
357  QString str = QStringLiteral( "<QgsProviderRegistry.ProviderCandidateDetails: %1>" ).arg( sipCpp->metadata()->key() );
358  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
359  % End
360 #endif
361 
362  private:
363  QgsProviderMetadata *mMetadata = nullptr;
364 
365  QList< QgsMapLayerType > mLayerTypes;
366 
367  };
368 
385  QList< QgsProviderRegistry::ProviderCandidateDetails > preferredProvidersForUri( const QString &uri ) const;
386 
398  class CORE_EXPORT UnusableUriDetails
399  {
400  public:
401 
408  UnusableUriDetails( const QString &uri = QString(), const QString &warning = QString(), const QList< QgsMapLayerType > &layerTypes = QList< QgsMapLayerType >() )
409  : uri( uri )
410  , warning( warning )
411  , layerTypes( layerTypes )
412  {}
413 
417  QString uri;
418 
422  QString warning;
423 
428 
433  QList<QgsMapLayerType> layerTypes;
434 
435 #ifdef SIP_RUN
436  SIP_PYOBJECT __repr__();
437  % MethodCode
438  QString str = QStringLiteral( "<QgsProviderRegistry.UnusableUriDetails: %1>" ).arg( sipCpp->warning );
439  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
440  % End
441 #endif
442 
443  };
444 
457  class CORE_EXPORT UnusableUriHandlerInterface
458  {
459 
460  public:
461 
462  virtual ~UnusableUriHandlerInterface() = default;
463 
467  virtual bool matchesUri( const QString &uri ) const = 0;
468 
472  virtual UnusableUriDetails details( const QString &uri ) const = 0;
473 
474  };
475 
486  bool registerUnusableUriHandler( UnusableUriHandlerInterface *handler SIP_TRANSFER );
487 
511  bool handleUnusableUri( const QString &uri, UnusableUriDetails &details SIP_OUT ) const;
512 
529  bool shouldDeferUriForOtherProviders( const QString &uri, const QString &providerKey ) const;
530 
544  bool uriIsBlocklisted( const QString &uri ) const;
545 
556  QString fileVectorFilters() const;
557 
570  QString fileRasterFilters() const;
571 
585  QString fileMeshFilters() const;
586 
597  QString fileMeshDatasetFilters() const;
598 
611  QString filePointCloudFilters() const;
612 
614  QString databaseDrivers() const;
616  QString directoryDrivers() const;
618  QString protocolDrivers() const;
619 
623  Q_DECL_DEPRECATED void registerGuis( QWidget *widget ) SIP_DEPRECATED;
624 
631  bool registerProvider( QgsProviderMetadata *providerMetadata SIP_TRANSFER );
632 
634  SIP_SKIP typedef std::map<QString, QgsProviderMetadata *> Providers;
635 
636  private:
638  QgsProviderRegistry( const QString &pluginPath );
639 
640 #ifdef SIP_RUN
641  QgsProviderRegistry( const QString &pluginPath );
642 #endif
643 
644  void init();
645  void clean();
646 
648  Providers mProviders;
649 
651  QDir mLibraryDirectory;
652 
662  QString mVectorFileFilters;
663 
667  QString mRasterFileFilters;
668 
672  QString mMeshFileFilters;
673 
677  QString mMeshDatasetFileFilters;
678 
682  QString mPointCloudFileFilters;
683 
690  QString mDatabaseDrivers;
691 
697  QString mDirectoryDrivers;
698 
705  QString mProtocolDrivers;
706 
707  QList< UnusableUriHandlerInterface * > mUnusableUriHandlers;
708 
712  static bool exists();
713 
714  friend class QgsApplication;
715 
716 }; // class QgsProviderRegistry
717 
718 #endif //QGSPROVIDERREGISTRY_H
719 
The Qgis class provides global constants for use throughout the application.
Definition: qgis.h:62
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.
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().
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.