QGIS API Documentation  3.25.0-Master (dec16ba68b)
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 
348  class CORE_EXPORT ProviderCandidateDetails
349  {
350 
351  public:
352 
356  ProviderCandidateDetails( QgsProviderMetadata *metadata, const QList< QgsMapLayerType > &layerTypes )
357  : mMetadata( metadata )
358  , mLayerTypes( layerTypes )
359  {}
360 
364  QgsProviderMetadata *metadata() const { return mMetadata; }
365 
370  QList<QgsMapLayerType> layerTypes() const { return mLayerTypes; }
371 
372 #ifdef SIP_RUN
373  SIP_PYOBJECT __repr__();
374  % MethodCode
375  QString str = QStringLiteral( "<QgsProviderRegistry.ProviderCandidateDetails: %1>" ).arg( sipCpp->metadata()->key() );
376  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
377  % End
378 #endif
379 
380  private:
381  QgsProviderMetadata *mMetadata = nullptr;
382 
383  QList< QgsMapLayerType > mLayerTypes;
384 
385  };
386 
403  QList< QgsProviderRegistry::ProviderCandidateDetails > preferredProvidersForUri( const QString &uri ) const;
404 
416  class CORE_EXPORT UnusableUriDetails
417  {
418  public:
419 
426  UnusableUriDetails( const QString &uri = QString(), const QString &warning = QString(), const QList< QgsMapLayerType > &layerTypes = QList< QgsMapLayerType >() )
427  : uri( uri )
428  , warning( warning )
429  , layerTypes( layerTypes )
430  {}
431 
435  QString uri;
436 
440  QString warning;
441 
446 
451  QList<QgsMapLayerType> layerTypes;
452 
453 #ifdef SIP_RUN
454  SIP_PYOBJECT __repr__();
455  % MethodCode
456  QString str = QStringLiteral( "<QgsProviderRegistry.UnusableUriDetails: %1>" ).arg( sipCpp->warning );
457  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
458  % End
459 #endif
460 
461  };
462 
475  class CORE_EXPORT UnusableUriHandlerInterface
476  {
477 
478  public:
479 
480  virtual ~UnusableUriHandlerInterface() = default;
481 
485  virtual bool matchesUri( const QString &uri ) const = 0;
486 
490  virtual UnusableUriDetails details( const QString &uri ) const = 0;
491 
492  };
493 
504  bool registerUnusableUriHandler( UnusableUriHandlerInterface *handler SIP_TRANSFER );
505 
529  bool handleUnusableUri( const QString &uri, UnusableUriDetails &details SIP_OUT ) const;
530 
547  bool shouldDeferUriForOtherProviders( const QString &uri, const QString &providerKey ) const;
548 
562  bool uriIsBlocklisted( const QString &uri ) const;
563 
575  QList< QgsProviderSublayerDetails > querySublayers( const QString &uri, Qgis::SublayerQueryFlags flags = Qgis::SublayerQueryFlags(), QgsFeedback *feedback = nullptr ) const;
576 
587  QString fileVectorFilters() const;
588 
601  QString fileRasterFilters() const;
602 
616  QString fileMeshFilters() const;
617 
628  QString fileMeshDatasetFilters() const;
629 
642  QString filePointCloudFilters() const;
643 
645  QString databaseDrivers() const;
647  QString directoryDrivers() const;
649  QString protocolDrivers() const;
650 
654  Q_DECL_DEPRECATED void registerGuis( QWidget *widget ) SIP_DEPRECATED;
655 
662  bool registerProvider( QgsProviderMetadata *providerMetadata SIP_TRANSFER );
663 
665  SIP_SKIP typedef std::map<QString, QgsProviderMetadata *> Providers;
666 
667  private:
669  QgsProviderRegistry( const QString &pluginPath );
670 
671 #ifdef SIP_RUN
672  QgsProviderRegistry( const QString &pluginPath );
673 #endif
674 
675  void init();
676  void clean();
677 
679  Providers mProviders;
680 
682  QDir mLibraryDirectory;
683 
693  QString mVectorFileFilters;
694 
698  QString mRasterFileFilters;
699 
703  QString mMeshFileFilters;
704 
708  QString mMeshDatasetFileFilters;
709 
713  QString mPointCloudFileFilters;
714 
721  QString mDatabaseDrivers;
722 
728  QString mDirectoryDrivers;
729 
736  QString mProtocolDrivers;
737 
738  QList< UnusableUriHandlerInterface * > mUnusableUriHandlers;
739 
743  static bool exists();
744 
745  friend class QgsApplication;
746 
747 }; // class QgsProviderRegistry
748 
749 #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
#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.