Branch data Line data Source code
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 "qgsdataitem.h"
27 : : #include "qgsdatasourceuri.h"
28 : : #include "qgscoordinatetransformcontext.h"
29 : : #include "qgslayermetadata.h"
30 : : #include "qgserror.h"
31 : :
32 : : class QgsRectangle;
33 : : class QgsCoordinateReferenceSystem;
34 : : class QgsDataProviderTemporalCapabilities;
35 : :
36 : :
37 : : /**
38 : : * \ingroup core
39 : : * \brief Abstract base class for spatial data provider implementations.
40 : : */
41 : 0 : class CORE_EXPORT QgsDataProvider : public QObject
42 : : {
43 : :
44 : : #ifdef SIP_RUN
45 : : SIP_CONVERT_TO_SUBCLASS_CODE
46 : : if ( qobject_cast<QgsVectorDataProvider *>( sipCpp ) )
47 : : {
48 : : sipType = sipType_QgsVectorDataProvider;
49 : : }
50 : : else if ( qobject_cast<QgsRasterDataProvider *>( sipCpp ) )
51 : : {
52 : : sipType = sipType_QgsRasterDataProvider;
53 : : }
54 : : else if ( qobject_cast<QgsMeshDataProvider *>( sipCpp ) )
55 : : {
56 : : sipType = sipType_QgsMeshDataProvider;
57 : : }
58 : : else if ( qobject_cast<QgsPointCloudDataProvider *>( sipCpp ) )
59 : : {
60 : : sipType = sipType_QgsPointCloudDataProvider;
61 : : }
62 : : else
63 : : {
64 : : sipType = 0;
65 : : }
66 : : SIP_END
67 : : #endif
68 : : Q_OBJECT
69 : :
70 : : public:
71 : :
72 : : // TODO QGIS 4: (re)move DataCapability as this enum is really meant for data items rather than data providers
73 : :
74 : : /**
75 : : * Used in browser model to understand which items for which providers should be populated
76 : : */
77 : : enum DataCapability
78 : : {
79 : : NoDataCapabilities = 0,
80 : : File = 1,
81 : : Dir = 1 << 1,
82 : : Database = 1 << 2,
83 : : Net = 1 << 3 // Internet source
84 : : };
85 : : Q_DECLARE_FLAGS( DataCapabilities, DataCapability )
86 : :
87 : : /**
88 : : * Properties are used to pass custom configuration options into data providers.
89 : : * This enum defines a list of custom properties which can be used on different
90 : : * providers. It depends on the provider, which properties are supported.
91 : : * In addition to these default properties, providers can add their custom properties
92 : : * starting from CustomData.
93 : : */
94 : : enum ProviderProperty
95 : : {
96 : : EvaluateDefaultValues, //!< Evaluate default values on provider side when calling QgsVectorDataProvider::defaultValue( int index ) rather than on commit.
97 : : CustomData = 3000 //!< Custom properties for 3rd party providers or very provider-specific properties which are not expected to be of interest for other providers can be added starting from this value up.
98 : : };
99 : :
100 : :
101 : : /**
102 : : * Setting options for creating vector data providers.
103 : : *
104 : : * \note coordinateTransformContext was added in QGIS 3.8
105 : : *
106 : : * \since QGIS 3.2
107 : : */
108 : 78 : struct ProviderOptions
109 : : {
110 : :
111 : : /**
112 : : * Coordinate transform context
113 : : */
114 : : QgsCoordinateTransformContext transformContext;
115 : :
116 : : };
117 : :
118 : : /**
119 : : * Flags which control dataprovider construction.
120 : : * \since QGIS 3.16
121 : : */
122 : : enum ReadFlag
123 : : {
124 : : FlagTrustDataSource = 1 << 0, //!< Trust datasource config (primary key unicity, geometry type and srid, etc). Improves provider load time by skipping expensive checks like primary key unicity, geometry type and srid and by using estimated metadata on data load. Since QGIS 3.16
125 : : SkipFeatureCount = 1 << 1, //!< Make featureCount() return -1 to indicate unknown, and subLayers() to return a unknown feature count as well. Since QGIS 3.18. Only implemented by OGR provider at time of writing.
126 : : };
127 : : Q_DECLARE_FLAGS( ReadFlags, ReadFlag )
128 : :
129 : : /**
130 : : * Create a new dataprovider with the specified in the \a uri.
131 : : *
132 : : * Additional creation options are specified within the \a options value and since QGIS 3.16 creation flags are specified within the \a flags value.
133 : : */
134 : : QgsDataProvider( const QString &uri = QString(),
135 : : const QgsDataProvider::ProviderOptions &providerOptions = QgsDataProvider::ProviderOptions(),
136 : : QgsDataProvider::ReadFlags flags = QgsDataProvider::ReadFlags() );
137 : :
138 : : /**
139 : : * Returns the coordinate system for the data source.
140 : : * If the provider isn't capable of returning its projection then an invalid
141 : : * QgsCoordinateReferenceSystem will be returned.
142 : : */
143 : : virtual QgsCoordinateReferenceSystem crs() const = 0;
144 : :
145 : : /**
146 : : * Set the data source specification. This may be a path or database
147 : : * connection string
148 : : * \param uri source specification
149 : : */
150 : 0 : virtual void setDataSourceUri( const QString &uri )
151 : : {
152 : 0 : mDataSourceURI = uri;
153 : 0 : }
154 : :
155 : : /**
156 : : * Gets the data source specification. This may be a path or database
157 : : * connection string
158 : : * \param expandAuthConfig Whether to expand any assigned authentication configuration
159 : : * \returns data source specification
160 : : * \note The default authentication configuration expansion is FALSE. This keeps credentials
161 : : * out of layer data source URIs and project files. Expansion should be specifically done
162 : : * only when needed within a provider
163 : : */
164 : 0 : virtual QString dataSourceUri( bool expandAuthConfig = false ) const
165 : : {
166 : 0 : if ( expandAuthConfig && mDataSourceURI.contains( QLatin1String( "authcfg" ) ) )
167 : : {
168 : 0 : const QgsDataSourceUri uri( mDataSourceURI );
169 : 0 : return uri.uri( expandAuthConfig );
170 : 0 : }
171 : : else
172 : : {
173 : 0 : return mDataSourceURI;
174 : : }
175 : 0 : }
176 : :
177 : : /**
178 : : * Returns a short comment for the data that this provider is
179 : : * providing access to (e.g. the comment for postgres table).
180 : : *
181 : : * \note The default implementation returns an empty string.
182 : : * \since QGIS 3.14
183 : : */
184 : : virtual QString dataComment() const { return QString(); };
185 : :
186 : :
187 : : /**
188 : : * Set the data source specification.
189 : : *
190 : : * \since QGIS 3.0
191 : : */
192 : : void setUri( const QgsDataSourceUri &uri )
193 : : {
194 : : mDataSourceURI = uri.uri( true );
195 : : }
196 : :
197 : : /**
198 : : * Gets the data source specification.
199 : : *
200 : : * \since QGIS 3.0
201 : : */
202 : : QgsDataSourceUri uri() const
203 : : {
204 : : return QgsDataSourceUri( mDataSourceURI );
205 : : }
206 : :
207 : : /**
208 : : * Returns the provider's temporal capabilities.
209 : : *
210 : : * This may be NULLPTR, depending on the data provider.
211 : : *
212 : : * \since QGIS 3.14
213 : : */
214 : : virtual QgsDataProviderTemporalCapabilities *temporalCapabilities();
215 : :
216 : : /**
217 : : * Returns the provider's temporal capabilities.
218 : : *
219 : : * This may be NULLPTR, depending on the data provider.
220 : : *
221 : : * \since QGIS 3.14
222 : : */
223 : : virtual const QgsDataProviderTemporalCapabilities *temporalCapabilities() const SIP_SKIP;
224 : :
225 : : /**
226 : : * Returns the extent of the layer
227 : : * \returns QgsRectangle containing the extent of the layer
228 : : */
229 : : virtual QgsRectangle extent() const = 0;
230 : :
231 : :
232 : : /**
233 : : * Returns TRUE if this is a valid layer. It is up to individual providers
234 : : * to determine what constitutes a valid layer.
235 : : */
236 : : virtual bool isValid() const = 0;
237 : :
238 : :
239 : : /**
240 : : * Update the extents of the layer. Not implemented by default.
241 : : */
242 : : virtual void updateExtents()
243 : : {
244 : : // NOP by default
245 : : }
246 : :
247 : :
248 : : /**
249 : : * Set the subset string used to create a subset of features in
250 : : * the layer. This may be a sql where clause or any other string
251 : : * that can be used by the data provider to create a subset.
252 : : * Must be implemented in the dataprovider.
253 : : */
254 : : virtual bool setSubsetString( const QString &subset, bool updateFeatureCount = true )
255 : : {
256 : : // NOP by default
257 : : Q_UNUSED( subset )
258 : : Q_UNUSED( updateFeatureCount )
259 : : return false;
260 : : }
261 : :
262 : :
263 : : /**
264 : : * Returns TRUE if the provider supports setting of subset strings.
265 : : */
266 : : virtual bool supportsSubsetString() const { return false; }
267 : :
268 : : /**
269 : : * Returns the subset definition string (typically sql) currently in
270 : : * use by the layer and used by the provider to limit the feature set.
271 : : * Must be overridden in the dataprovider, otherwise returns a null
272 : : * QString.
273 : : */
274 : : virtual QString subsetString() const
275 : : {
276 : : return QString();
277 : : }
278 : :
279 : :
280 : : /**
281 : : * Sub-layers handled by this provider, in order from bottom to top
282 : : *
283 : : * Sub-layers are used when the provider's source can combine layers
284 : : * it knows about in some way before it hands them off to the provider.
285 : : *
286 : : * \see SUBLAYER_SEPARATOR
287 : : */
288 : : virtual QStringList subLayers() const
289 : : {
290 : : return QStringList(); // Empty
291 : : }
292 : :
293 : : /**
294 : : * Sub-layer styles for each sub-layer handled by this provider,
295 : : * in order from bottom to top
296 : : *
297 : : * Sub-layer styles are used to abstract the way the provider's source can symbolise
298 : : * layers in some way at the server, before it serves them to the provider.
299 : : */
300 : : virtual QStringList subLayerStyles() const
301 : : {
302 : : return QStringList(); // Empty
303 : : }
304 : :
305 : :
306 : : /**
307 : : * Returns the number of layers for the current data source
308 : : */
309 : : virtual uint subLayerCount() const
310 : : {
311 : : return 0;
312 : : }
313 : :
314 : :
315 : : /**
316 : : * Reorder the list of layer names to be rendered by this provider
317 : : * (in order from bottom to top)
318 : : * \note layers must have been previously added.
319 : : */
320 : : virtual void setLayerOrder( const QStringList &layers )
321 : : {
322 : : //prevent unused var warnings
323 : : if ( layers.count() < 1 )
324 : : {
325 : : return;
326 : : }
327 : : // NOOP
328 : : }
329 : :
330 : :
331 : : /**
332 : : * Set the visibility of the given sublayer name
333 : : */
334 : : virtual void setSubLayerVisibility( const QString &name, bool vis )
335 : : {
336 : : //prevent unused var warnings
337 : : if ( name.isEmpty() || !vis )
338 : : {
339 : : return;
340 : : }
341 : : // NOOP
342 : : }
343 : :
344 : :
345 : : /**
346 : : * Returns a provider name
347 : : *
348 : : * Essentially just returns the provider key. Should be used to build file
349 : : * dialogs so that providers can be shown with their supported types. Thus
350 : : * if more than one provider supports a given format, the user is able to
351 : : * select a specific provider to open that file.
352 : : *
353 : : * \note
354 : : *
355 : : * Instead of being pure virtual, might be better to generalize this
356 : : * behavior and presume that none of the sub-classes are going to do
357 : : * anything strange with regards to their name or description?
358 : : *
359 : : */
360 : : virtual QString name() const = 0;
361 : :
362 : :
363 : : /**
364 : : * Returns description
365 : : *
366 : : * Returns a terse string describing what the provider is.
367 : : *
368 : : * \note
369 : : *
370 : : * Instead of being pure virtual, might be better to generalize this
371 : : * behavior and presume that none of the sub-classes are going to do
372 : : * anything strange with regards to their name or description?
373 : : *
374 : : */
375 : : virtual QString description() const = 0;
376 : :
377 : :
378 : : /**
379 : : * Returns vector file filter string
380 : : *
381 : : * Returns a string suitable for a QFileDialog of vector file formats
382 : : * supported by the data provider. Naturally this will be an empty string
383 : : * for those data providers that do not deal with plain files, such as
384 : : * databases and servers.
385 : : *
386 : : * \note It'd be nice to eventually be raster/vector neutral.
387 : : */
388 : : virtual QString fileVectorFilters() const
389 : : {
390 : : return QString();
391 : : }
392 : :
393 : :
394 : : /**
395 : : * Returns raster file filter string
396 : : *
397 : : * Returns a string suitable for a QFileDialog of raster file formats
398 : : * supported by the data provider. Naturally this will be an empty string
399 : : * for those data providers that do not deal with plain files, such as
400 : : * databases and servers.
401 : : *
402 : : * \note It'd be nice to eventually be raster/vector neutral.
403 : : */
404 : : virtual QString fileRasterFilters() const
405 : : {
406 : : return QString();
407 : : }
408 : :
409 : : // TODO QGIS 4 -> Make `reloadData()` non virtual. This should be implemented in `reloadProviderData()`.
410 : :
411 : : /**
412 : : * Reloads the data from the source for providers with data caches to synchronize,
413 : : * changes in the data source, feature counts and other specific actions.
414 : : * Emits the `dataChanged` signal
415 : : *
416 : : * \note only available for providers which implement the reloadProviderData() method.
417 : : */
418 : : virtual void reloadData();
419 : :
420 : : //! Time stamp of data source in the moment when data/metadata were loaded by provider
421 : : virtual QDateTime timestamp() const { return mTimestamp; }
422 : :
423 : : //! Current time stamp of data source
424 : : virtual QDateTime dataTimestamp() const { return QDateTime(); }
425 : :
426 : : /**
427 : : * Gets current status error. This error describes some principal problem
428 : : * for which provider cannot work and thus is not valid. It is not last error
429 : : * after accessing data by block(), identify() etc.
430 : : */
431 : : virtual QgsError error() const { return mError; }
432 : :
433 : : /**
434 : : * Invalidate connections corresponding to specified name
435 : : * \since QGIS 2.16
436 : : */
437 : : virtual void invalidateConnections( const QString &connection ) { Q_UNUSED( connection ) }
438 : :
439 : : /**
440 : : * Enter update mode.
441 : : *
442 : : * This is aimed at providers that can open differently the connection to
443 : : * the datasource, according it to be in update mode or in read-only mode.
444 : : * A call to this method shall be balanced with a call to leaveUpdateMode(),
445 : : * if this method returns TRUE.
446 : : *
447 : : * Most providers will have an empty implementation for that method.
448 : : *
449 : : * For backward compatibility, providers that implement enterUpdateMode() should
450 : : * still make sure to allow editing operations to work even if enterUpdateMode()
451 : : * is not explicitly called.
452 : : *
453 : : * Several successive calls to enterUpdateMode() can be done. So there is
454 : : * a concept of stack of calls that must be handled by the provider. Only the first
455 : : * call to enterUpdateMode() will really turn update mode on.
456 : : *
457 : : * \returns TRUE in case of success (or no-op implementation), FALSE in case of failure.
458 : : *
459 : : * \since QGIS 2.16
460 : : */
461 : : virtual bool enterUpdateMode() { return true; }
462 : :
463 : : /**
464 : : * Leave update mode.
465 : : *
466 : : * This is aimed at providers that can open differently the connection to
467 : : * the datasource, according it to be in update mode or in read-only mode.
468 : : * This method shall be balanced with a successful call to enterUpdateMode().
469 : : *
470 : : * Most providers will have an empty implementation for that method.
471 : : *
472 : : * Several successive calls to enterUpdateMode() can be done. So there is
473 : : * a concept of stack of calls that must be handled by the provider. Only the last
474 : : * call to leaveUpdateMode() will really turn update mode off.
475 : : *
476 : : * \returns TRUE in case of success (or no-op implementation), FALSE in case of failure.
477 : : *
478 : : * \since QGIS 2.16
479 : : */
480 : : virtual bool leaveUpdateMode() { return true; }
481 : :
482 : : /**
483 : : * Allows setting arbitrary properties on the provider.
484 : : * It depends on the provider which properties are supported.
485 : : *
486 : : * \since QGIS 2.16
487 : : */
488 : : void setProviderProperty( ProviderProperty property, const QVariant &value );
489 : :
490 : : /**
491 : : * Allows setting arbitrary properties on the provider.
492 : : * It depends on the provider which properties are supported.
493 : : *
494 : : * \since QGIS 2.16
495 : : */
496 : : void setProviderProperty( int property, const QVariant &value ); // SIP_SKIP
497 : :
498 : : /**
499 : : * Gets the current value of a certain provider property.
500 : : * It depends on the provider which properties are supported.
501 : : *
502 : : * \since QGIS 2.16
503 : : */
504 : : QVariant providerProperty( ProviderProperty property, const QVariant &defaultValue = QVariant() ) const;
505 : :
506 : : /**
507 : : * Gets the current value of a certain provider property.
508 : : * It depends on the provider which properties are supported.
509 : : *
510 : : * \since QGIS 2.16
511 : : */
512 : : QVariant providerProperty( int property, const QVariant &defaultValue ) const; // SIP_SKIP
513 : :
514 : : /**
515 : : * Set whether the provider will listen to datasource notifications
516 : : * If set, the provider will issue notify signals.
517 : : *
518 : : * The default implementation does nothing.
519 : : *
520 : : * \see notify
521 : : *
522 : : * \since QGIS 3.0
523 : : */
524 : : virtual void setListening( bool isListening );
525 : :
526 : : #ifndef SIP_RUN
527 : :
528 : : /**
529 : : * Stores settings related to the context in which a preview job runs.
530 : : * \note Not available in Python bindings
531 : : * \since QGIS 3.0
532 : : */
533 : : struct PreviewContext
534 : : {
535 : : //! Previous rendering time for the layer, in ms
536 : : double lastRenderingTimeMs = -1;
537 : :
538 : : //! Default maximum allowable render time, in ms
539 : : double maxRenderingTimeMs = MAXIMUM_LAYER_PREVIEW_TIME_MS;
540 : : };
541 : : #endif
542 : :
543 : : /**
544 : : * Returns whether the layer must be rendered in preview jobs.
545 : : *
546 : : * The \a context argument gives useful information which can be used
547 : : * to determine whether the layer should be rendered or not.
548 : : *
549 : : * The base implementation returns TRUE if lastRenderingTimeMs <= maxRenderingTimeMs.
550 : : *
551 : : *
552 : : * \note not available in Python bindings
553 : : * \since QGIS 3.0
554 : : */
555 : : virtual bool renderInPreview( const QgsDataProvider::PreviewContext &context ); // SIP_SKIP
556 : :
557 : : /**
558 : : * Returns layer metadata collected from the provider's source.
559 : : *
560 : : * Individual data providers must implement this method if they support collecting metadata.
561 : : *
562 : : * \see writeLayerMetadata()
563 : : * \since QGIS 3.0
564 : : */
565 : : virtual QgsLayerMetadata layerMetadata() const { return QgsLayerMetadata(); }
566 : :
567 : : /**
568 : : * Writes layer \a metadata to the underlying provider source. Support depends
569 : : * on individual provider capabilities.
570 : : *
571 : : * Returns TRUE if metadata was successfully written to the data provider.
572 : : * \see layerMetadata()
573 : : * \since QGIS 3.0
574 : : */
575 : : virtual bool writeLayerMetadata( const QgsLayerMetadata &metadata ) { Q_UNUSED( metadata ) return false; }
576 : :
577 : : /**
578 : : * Returns data provider coordinate transform context
579 : : *
580 : : * \see setTransformContext()
581 : : * \note not available in Python bindings
582 : : * \since QGIS 3.8
583 : : */
584 : : QgsCoordinateTransformContext transformContext() const SIP_SKIP;
585 : :
586 : : /**
587 : : * Sets data coordinate transform context to \a transformContext
588 : : *
589 : : * The default implementation is a simple setter, subclasses may override to perform
590 : : * additional actions required by a change of coordinate transform context.
591 : : *
592 : : * \see transformContext()
593 : : * \note not available in Python bindings
594 : : * \since QGIS 3.8
595 : : */
596 : : virtual void setTransformContext( const QgsCoordinateTransformContext &transformContext ) SIP_SKIP;
597 : :
598 : : /**
599 : : * String sequence used for separating components of sublayers strings.
600 : : * \note Replaces the static const SUBLAYER_SEPARATOR
601 : : * \see subLayers()
602 : : * \since QGIS 3.12
603 : : */
604 : : static QString sublayerSeparator();
605 : :
606 : : signals:
607 : :
608 : : /**
609 : : * Emitted whenever a deferred extent calculation is completed by the provider.
610 : : *
611 : : * Layers should connect to this signal and update their cached extents whenever
612 : : * it is emitted.
613 : : */
614 : : void fullExtentCalculated();
615 : :
616 : : /**
617 : : * Emitted whenever a change is made to the data provider which may have
618 : : * caused changes in the provider's data OUTSIDE of QGIS.
619 : : *
620 : : * When emitted from a QgsVectorDataProvider, any cached information such as
621 : : * feature ids should be invalidated.
622 : : *
623 : : * \warning This signal is NOT emitted when changes are made to a provider
624 : : * from INSIDE QGIS -- e.g. when adding features to a vector layer, deleting features
625 : : * or modifying existing features. Instead, the specific QgsVectorLayer signals
626 : : * should be used to detect these operations.
627 : : */
628 : : void dataChanged();
629 : :
630 : : /**
631 : : * Emitted when the datasource issues a notification.
632 : : *
633 : : * \see setListening
634 : : *
635 : : * \since QGIS 3.0
636 : : */
637 : : void notify( const QString &msg );
638 : :
639 : :
640 : : protected:
641 : :
642 : : /**
643 : : * Timestamp of data in the moment when the data were loaded by provider.
644 : : */
645 : : QDateTime mTimestamp;
646 : :
647 : : //! \brief Error
648 : : QgsError mError;
649 : :
650 : : //! Add error message
651 : 0 : void appendError( const QgsErrorMessage &message ) { mError.append( message ); }
652 : :
653 : : //! Sets error message
654 : 0 : void setError( const QgsError &error ) { mError = error;}
655 : :
656 : : //! Read flags. It's up to the subclass to respect these when needed
657 : : QgsDataProvider::ReadFlags mReadFlags = QgsDataProvider::ReadFlags();
658 : :
659 : : private:
660 : :
661 : : /**
662 : : * Universal Resource Identifier for source data.
663 : : * This could be a file, database, or server address.
664 : : */
665 : : QString mDataSourceURI;
666 : :
667 : : QgsDataProvider::ProviderOptions mOptions;
668 : :
669 : : QMap< int, QVariant > mProviderProperties;
670 : :
671 : : /**
672 : : * Protects options from being accessed concurrently
673 : : */
674 : : mutable QMutex mOptionsMutex;
675 : :
676 : : /**
677 : : * Reloads the data according to the provider
678 : : * \since QGIS 3.12
679 : : */
680 : : virtual void reloadProviderData() {}
681 : : };
682 : :
683 : : Q_DECLARE_OPERATORS_FOR_FLAGS( QgsDataProvider::ReadFlags )
684 : :
685 : : #endif
|
