class QgsDataProvider : QObject { %TypeHeaderCode #include %End %ConvertToSubClassCode if (sipCpp->inherits("QgsVectorDataProvider")) { sipType = sipType_QgsVectorDataProvider; } else if (sipCpp->inherits("QgsRasterDataProvider")) { sipType = sipType_QgsRasterDataProvider; } else { sipType = 0; } %End public: enum DataCapability { NoDataCapabilities, File, Dir, Database, Net }; /** * Properties are used to pass custom configuration options into data providers. * This enum defines a list of custom properties which can be used on different * providers. It depends on the provider, which properties are supported. * In addition to these default properties, providers can add their custom properties * starting from CustomData. */ enum ProviderProperty { EvaluateDefaultValues, //!< Evaluate default values on provider side when calling QgsVectorDataProvider::defaultValue( int index ) rather than on commit. 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. }; QgsDataProvider( const QString & uri = "" ); /** * We need this so the subclass destructors get called */ virtual ~QgsDataProvider(); /* Returns the coordinate system for the data source. * If the provider isn't capable of returning its projection then an invalid * QgsCoordinateReferenceSystem will be returned. */ virtual QgsCoordinateReferenceSystem crs() const = 0; /** * Set the data source specification. This may be a path or database * connection string * @param uri source specification */ virtual void setDataSourceUri( const QString & uri ); /** * Get the data source specification. This may be a path or database * connection string * @param expandAuthConfig Whether to expand any assigned authentication configuration * @return data source specification * @note The default authentication configuration expansion is FALSE. This keeps credentials * out of layer data source URIs and project files. Expansion should be specifically done * only when needed within a provider */ virtual QString dataSourceUri( bool expandAuthConfig = true ) const; /** * Returns the extent of the layer. * @return QgsRectangle containing the extent of the layer */ virtual QgsRectangle extent() const = 0; /** * Returns true if this is a valid layer. It is up to individual providers * to determine what constitutes a valid layer. */ virtual bool isValid() const = 0; /** * Update the extents of the layer. Not implemented by default. */ virtual void updateExtents(); /** * Set the subset string used to create a subset of features in * the layer. This may be a sql where clause or any other string * that can be used by the data provider to create a subset. * Must be implemented in the dataprovider. */ virtual bool setSubsetString( const QString& subset, bool updateFeatureCount = true ); /** Returns true if the provider supports setting of subset strings. */ virtual bool supportsSubsetString() const; /** * Returns the subset definition string (typically sql) currently in * use by the layer and used by the provider to limit the feature set. * Must be overridden in the dataprovider, otherwise returns a null * QString. */ virtual QString subsetString() const; /** * Sub-layers handled by this provider, in order from bottom to top * * Sub-layers are used when the provider's source can combine layers * it knows about in some way before it hands them off to the provider. */ virtual QStringList subLayers() const; /** * Sub-layer styles for each sub-layer handled by this provider, * in order from bottom to top * * Sub-layer styles are used to abstract the way the provider's source can symbolise * layers in some way at the server, before it serves them to the provider. */ virtual QStringList subLayerStyles() const; /** * return the number of layers for the current data source */ virtual uint subLayerCount() const; /** * Reorder the list of layer names to be rendered by this provider * (in order from bottom to top) * \note layers must have been previously added. */ virtual void setLayerOrder( const QStringList &layers ); /** * Set the visibility of the given sublayer name */ virtual void setSubLayerVisibility( const QString &name, bool vis ); /** Return a provider name * * Essentially just returns the provider key. Should be used to build file * dialogs so that providers can be shown with their supported types. Thus * if more than one provider supports a given format, the user is able to * select a specific provider to open that file. * * @note * * Instead of being pure virtual, might be better to generalize this * behavior and presume that none of the sub-classes are going to do * anything strange with regards to their name or description? * */ virtual QString name() const = 0; /** Return description * * Return a terse string describing what the provider is. * * @note * * Instead of being pure virtual, might be better to generalize this * behavior and presume that none of the sub-classes are going to do * anything strange with regards to their name or description? * */ virtual QString description() const = 0; /** Return vector file filter string * * Returns a string suitable for a QFileDialog of vector file formats * supported by the data provider. Naturally this will be an empty string * for those data providers that do not deal with plain files, such as * databases and servers. * * @note It'd be nice to eventually be raster/vector neutral. * */ virtual QString fileVectorFilters() const; /** Return raster file filter string * * Returns a string suitable for a QFileDialog of raster file formats * supported by the data provider. Naturally this will be an empty string * for those data providers that do not deal with plain files, such as * databases and servers. * * @note It'd be nice to eventually be raster/vector neutral. */ virtual QString fileRasterFilters() const; /** Reloads the data from the source. Needs to be implemented by providers with data caches to synchronize with changes in the data source*/ virtual void reloadData(); /** Time stamp of data source in the moment when data/metadata were loaded by provider */ virtual QDateTime timestamp() const; /** Current time stamp of data source */ virtual QDateTime dataTimestamp() const; /** Get current status error. This error describes some principal problem * for which provider cannot work and thus is not valid. It is not last error * after accessing data by block(), identify() etc. */ virtual QgsError error() const; /** Invalidate connections corresponding to specified name * @note added in QGIS 2.16 */ virtual void invalidateConnections( const QString& connection ); /** Enter update mode. * * This is aimed at providers that can open differently the connection to * the datasource, according it to be in update mode or in read-only mode. * A call to this method shall be balanced with a call to leaveUpdateMode(), * if this method returns true. * * Most providers will have an empty implementation for that method. * * For backward compatibility, providers that implement enterUpdateMode() should * still make sure to allow editing operations to work even if enterUpdateMode() * is not explicitly called. * * Several successive calls to enterUpdateMode() can be done. So there is * a concept of stack of calls that must be handled by the provider. Only the first * call to enterUpdateMode() will really turn update mode on. * * @return true in case of success (or no-op implementation), false in case of failure * * @note added in QGIS 2.16 */ virtual bool enterUpdateMode(); /** Leave update mode. * * This is aimed at providers that can open differently the connection to * the datasource, according it to be in update mode or in read-only mode. * This method shall be balanced with a successful call to enterUpdateMode(). * * Most providers will have an empty implementation for that method. * * Several successive calls to enterUpdateMode() can be done. So there is * a concept of stack of calls that must be handled by the provider. Only the last * call to leaveUpdateMode() will really turn update mode off. * * @return true in case of success (or no-op implementation), false in case of failure * * @note added in QGIS 2.16 */ virtual bool leaveUpdateMode(); /** * Allows setting arbitrary properties on the provider. * It depends on the provider which properties are supported. * * @note added in 2.16 */ void setProviderProperty( ProviderProperty property, const QVariant& value ); /** * Allows setting arbitrary properties on the provider. * It depends on the provider which properties are supported. * * @note added in 2.16 */ // void setProviderProperty( int property, const QVariant& value ); /** * Get the current value of a certain provider property. * It depends on the provider which properties are supported. * * @note added in 2.16 */ QVariant providerProperty( ProviderProperty property, const QVariant& defaultValue = QVariant() ) const; /** * Get the current value of a certain provider property. * It depends on the provider which properties are supported. * * @note added in 2.16 */ // QVariant providerProperty( int property , const QVariant& defaultValue ) const; signals: /** * This is emitted whenever the worker thread has fully calculated the * PostGIS extents for this layer, and its event has been received by this * provider. */ void fullExtentCalculated(); /** * This is emitted whenever an asynchronous operation has finished * and the data should be redrawn * * When emitted from a QgsVectorDataProvider, any cached information such as * feature ids should be invalidated. */ void dataChanged(); /** * This is emitted whenever data or metadata (e.g. color table, extent) has changed * @param changed binary combination of changes */ void dataChanged( int changed ); protected: /** Add error message */ void appendError( const QgsErrorMessage & theMessage ); /** Set error message */ void setError( const QgsError & theError ); };