QGIS API Documentation  3.19.0-Master (898a03ac22)
qgsdataprovider.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgsdataprovider.h - DataProvider Interface class
3  --------------------------------------
4  Date : 09-Sep-2003
5  Copyright : (C) 2003 by Gary E.Sherman
6  email : sherman at mrcc.com
7  ***************************************************************************
8  * *
9  * This program is free software; you can redistribute it and/or modify *
10  * it under the terms of the GNU General Public License as published by *
11  * the Free Software Foundation; either version 2 of the License, or *
12  * (at your option) any later version. *
13  * *
14  ***************************************************************************/
15 
16 #ifndef QQGSDATAPROVIDER_H
17 #define QQGSDATAPROVIDER_H
18 
19 #include "qgis_core.h"
20 #include <QDateTime>
21 #include <QObject>
22 #include <QString>
23 #include <QStringList>
24 #include <QMutex>
25 
26 #include "qgsdatasourceuri.h"
28 #include "qgslayermetadata.h"
29 #include "qgserror.h"
30 
31 class QgsRectangle;
34 
35 
40 class CORE_EXPORT QgsDataProvider : public QObject
41 {
42 
43 #ifdef SIP_RUN
45  if ( qobject_cast<QgsVectorDataProvider *>( sipCpp ) )
46  {
47  sipType = sipType_QgsVectorDataProvider;
48  }
49  else if ( qobject_cast<QgsRasterDataProvider *>( sipCpp ) )
50  {
51  sipType = sipType_QgsRasterDataProvider;
52  }
53  else if ( qobject_cast<QgsMeshDataProvider *>( sipCpp ) )
54  {
55  sipType = sipType_QgsMeshDataProvider;
56  }
57  else if ( qobject_cast<QgsPointCloudDataProvider *>( sipCpp ) )
58  {
59  sipType = sipType_QgsPointCloudDataProvider;
60  }
61  else
62  {
63  sipType = 0;
64  }
65  SIP_END
66 #endif
67  Q_OBJECT
68 
69  public:
70 
71  // TODO QGIS 4: (re)move DataCapability as this enum is really meant for data items rather than data providers
72 
77  {
78  NoDataCapabilities = 0,
79  File = 1,
80  Dir = 1 << 1,
81  Database = 1 << 2,
82  Net = 1 << 3 // Internet source
83  };
84  Q_DECLARE_FLAGS( DataCapabilities, DataCapability )
85 
86 
94  {
96  CustomData = 3000
97  };
98 
99 
108  {
109 
114 
115  };
116 
121  enum ReadFlag
122  {
123  FlagTrustDataSource = 1 << 0,
124  SkipFeatureCount = 1 << 1,
125  FlagLoadDefaultStyle = 1 << 2,
126  SkipGetExtent = 1 << 3,
127  };
128  Q_DECLARE_FLAGS( ReadFlags, ReadFlag )
129 
130 
135  QgsDataProvider( const QString &uri = QString(),
137  QgsDataProvider::ReadFlags flags = QgsDataProvider::ReadFlags() );
138 
144  virtual QgsCoordinateReferenceSystem crs() const = 0;
145 
151  virtual void setDataSourceUri( const QString &uri )
152  {
153  mDataSourceURI = uri;
154  }
155 
165  virtual QString dataSourceUri( bool expandAuthConfig = false ) const
166  {
167  if ( expandAuthConfig && mDataSourceURI.contains( QLatin1String( "authcfg" ) ) )
168  {
169  const QgsDataSourceUri uri( mDataSourceURI );
170  return uri.uri( expandAuthConfig );
171  }
172  else
173  {
174  return mDataSourceURI;
175  }
176  }
177 
185  virtual QString dataComment() const { return QString(); };
186 
187 
193  void setUri( const QgsDataSourceUri &uri )
194  {
195  mDataSourceURI = uri.uri( true );
196  }
197 
204  {
205  return QgsDataSourceUri( mDataSourceURI );
206  }
207 
215  virtual QgsDataProviderTemporalCapabilities *temporalCapabilities();
216 
224  virtual const QgsDataProviderTemporalCapabilities *temporalCapabilities() const SIP_SKIP;
225 
230  virtual QgsRectangle extent() const = 0;
231 
232 
237  virtual bool isValid() const = 0;
238 
239 
243  virtual void updateExtents()
244  {
245  // NOP by default
246  }
247 
248 
255  virtual bool setSubsetString( const QString &subset, bool updateFeatureCount = true )
256  {
257  // NOP by default
258  Q_UNUSED( subset )
259  Q_UNUSED( updateFeatureCount )
260  return false;
261  }
262 
263 
267  virtual bool supportsSubsetString() const { return false; }
268 
275  virtual QString subsetString() const
276  {
277  return QString();
278  }
279 
280 
289  virtual QStringList subLayers() const
290  {
291  return QStringList(); // Empty
292  }
293 
301  virtual QStringList subLayerStyles() const
302  {
303  return QStringList(); // Empty
304  }
305 
306 
310  virtual uint subLayerCount() const
311  {
312  return 0;
313  }
314 
315 
321  virtual void setLayerOrder( const QStringList &layers )
322  {
323  //prevent unused var warnings
324  if ( layers.count() < 1 )
325  {
326  return;
327  }
328  // NOOP
329  }
330 
331 
335  virtual void setSubLayerVisibility( const QString &name, bool vis )
336  {
337  //prevent unused var warnings
338  if ( name.isEmpty() || !vis )
339  {
340  return;
341  }
342  // NOOP
343  }
344 
345 
361  virtual QString name() const = 0;
362 
363 
376  virtual QString description() const = 0;
377 
378 
389  virtual QString fileVectorFilters() const
390  {
391  return QString();
392  }
393 
394 
405  virtual QString fileRasterFilters() const
406  {
407  return QString();
408  }
409 
410  // TODO QGIS 4 -> Make `reloadData()` non virtual. This should be implemented in `reloadProviderData()`.
411 
419  virtual void reloadData();
420 
422  virtual QDateTime timestamp() const { return mTimestamp; }
423 
425  virtual QDateTime dataTimestamp() const { return QDateTime(); }
426 
432  virtual QgsError error() const { return mError; }
433 
438  virtual void invalidateConnections( const QString &connection ) { Q_UNUSED( connection ) }
439 
462  virtual bool enterUpdateMode() { return true; }
463 
481  virtual bool leaveUpdateMode() { return true; }
482 
489  void setProviderProperty( ProviderProperty property, const QVariant &value );
490 
497  void setProviderProperty( int property, const QVariant &value ); // SIP_SKIP
498 
505  QVariant providerProperty( ProviderProperty property, const QVariant &defaultValue = QVariant() ) const;
506 
513  QVariant providerProperty( int property, const QVariant &defaultValue ) const; // SIP_SKIP
514 
525  virtual void setListening( bool isListening );
526 
527 #ifndef SIP_RUN
528 
535  {
537  double lastRenderingTimeMs = -1;
538 
540  double maxRenderingTimeMs = MAXIMUM_LAYER_PREVIEW_TIME_MS;
541  };
542 #endif
543 
556  virtual bool renderInPreview( const QgsDataProvider::PreviewContext &context ); // SIP_SKIP
557 
566  virtual QgsLayerMetadata layerMetadata() const { return QgsLayerMetadata(); }
567 
576  virtual bool writeLayerMetadata( const QgsLayerMetadata &metadata ) { Q_UNUSED( metadata ) return false; }
577 
585  QgsCoordinateTransformContext transformContext() const SIP_SKIP;
586 
597  virtual void setTransformContext( const QgsCoordinateTransformContext &transformContext ) SIP_SKIP;
598 
605  static QString sublayerSeparator();
606 
607  signals:
608 
615  void fullExtentCalculated();
616 
629  void dataChanged();
630 
638  void notify( const QString &msg );
639 
640 
641  protected:
642 
646  QDateTime mTimestamp;
647 
649  QgsError mError;
650 
652  void appendError( const QgsErrorMessage &message ) { mError.append( message ); }
653 
655  void setError( const QgsError &error ) { mError = error;}
656 
658  QgsDataProvider::ReadFlags mReadFlags = QgsDataProvider::ReadFlags();
659 
660  private:
661 
666  QString mDataSourceURI;
667 
669 
670  QMap< int, QVariant > mProviderProperties;
671 
675  mutable QMutex mOptionsMutex;
676 
681  virtual void reloadProviderData() {}
682 };
683 
684 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsDataProvider::ReadFlags )
685 
686 #endif
This class represents a coordinate reference system (CRS).
Contains information about the context in which a coordinate transform is executed.
Base class for handling properties relating to a data provider's temporal capabilities.
Abstract base class for spatial data provider implementations.
virtual void invalidateConnections(const QString &connection)
Invalidate connections corresponding to specified name.
virtual bool leaveUpdateMode()
Leave update mode.
void setUri(const QgsDataSourceUri &uri)
Set the data source specification.
virtual void setLayerOrder(const QStringList &layers)
Reorder the list of layer names to be rendered by this provider (in order from bottom to top)
ReadFlag
Flags which control dataprovider construction.
virtual QString name() const =0
Returns a provider name.
void setError(const QgsError &error)
Sets error message.
virtual QDateTime timestamp() const
Time stamp of data source in the moment when data/metadata were loaded by provider.
virtual QgsCoordinateReferenceSystem crs() const =0
Returns the coordinate system for the data source.
virtual QString dataComment() const
Returns a short comment for the data that this provider is providing access to (e....
ProviderProperty
Properties are used to pass custom configuration options into data providers.
@ EvaluateDefaultValues
Evaluate default values on provider side when calling QgsVectorDataProvider::defaultValue( int index ...
virtual QString subsetString() const
Returns the subset definition string (typically sql) currently in use by the layer and used by the pr...
virtual QgsLayerMetadata layerMetadata() const
Returns layer metadata collected from the provider's source.
virtual void setDataSourceUri(const QString &uri)
Set the data source specification.
virtual QString fileRasterFilters() const
Returns raster file filter string.
virtual QgsError error() const
Gets current status error.
DataCapability
Used in browser model to understand which items for which providers should be populated.
virtual QDateTime dataTimestamp() const
Current time stamp of data source.
virtual bool supportsSubsetString() const
Returns true if the provider supports setting of subset strings.
virtual QString dataSourceUri(bool expandAuthConfig=false) const
Gets the data source specification.
virtual QString description() const =0
Returns description.
QgsDataSourceUri uri() const
Gets the data source specification.
virtual QString fileVectorFilters() const
Returns vector file filter string.
virtual QStringList subLayerStyles() const
Sub-layer styles for each sub-layer handled by this provider, in order from bottom to top.
virtual bool setSubsetString(const QString &subset, bool updateFeatureCount=true)
Set the subset string used to create a subset of features in the layer.
virtual uint subLayerCount() const
Returns the number of layers for the current data source.
virtual QStringList subLayers() const
Sub-layers handled by this provider, in order from bottom to top.
virtual bool writeLayerMetadata(const QgsLayerMetadata &metadata)
Writes layer metadata to the underlying provider source.
virtual bool enterUpdateMode()
Enter update mode.
virtual void setSubLayerVisibility(const QString &name, bool vis)
Set the visibility of the given sublayer name.
Class for storing the component parts of a RDBMS data source URI (e.g.
QString uri(bool expandAuthConfig=true) const
Returns the complete URI as a string.
QgsErrorMessage represents single error message.
Definition: qgserror.h:33
QgsError is container for error messages (report).
Definition: qgserror.h:81
void append(const QString &message, const QString &tag)
Append new error message.
Definition: qgserror.cpp:39
A structured metadata store for a map layer.
A rectangle specified with double values.
Definition: qgsrectangle.h:42
#define SIP_CONVERT_TO_SUBCLASS_CODE(code)
Definition: qgis_sip.h:177
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_END
Definition: qgis_sip.h:194
Q_DECLARE_OPERATORS_FOR_FLAGS(QgsField::ConfigurationFlags) CORE_EXPORT QDataStream &operator<<(QDataStream &out
Writes the field to stream out. QGIS version compatibility is not guaranteed.
Stores settings related to the context in which a preview job runs.
Setting options for creating vector data providers.
QgsCoordinateTransformContext transformContext
Coordinate transform context.