QgsDataProvider class

Abstract base class for spatial data provider implementations.

Contents

Derived classes

class QgsMeshDataProvider
Base class for providing data for QgsMeshLayer.
class QgsRasterDataProvider
Base class for raster data providers.
class QgsVectorDataProvider
This is the base class for vector data providers.

Public types

struct PreviewContext
Stores settings related to the context in which a preview job runs.
struct ProviderOptions
Setting options for creating vector data providers.
enum ProviderProperty { EvaluateDefaultValues, CustomData = 3000 }
Properties are used to pass custom configuration options into data providers.

Public static variables

static QString SUBLAYER_SEPARATOR
String sequence used for separating components of sublayers strings.

Constructors, destructors, conversion operators

QgsDataProvider(const QString& uri = QString(), const QgsDataProvider::ProviderOptions& options = QgsDataProvider::ProviderOptions())
Create a new dataprovider with the specified in the uri.

Public functions

auto crs() const -> QgsCoordinateReferenceSystem pure virtual
Returns the coordinate system for the data source.
auto dataSourceUri(bool expandAuthConfig = false) const -> QString virtual
Gets the data source specification.
auto dataTimestamp() const -> QDateTime virtual
Current time stamp of data source.
auto description() const -> QString pure virtual
Returns description.
auto enterUpdateMode() -> bool virtual
Enter update mode.
auto error() const -> QgsError virtual
Gets current status error.
auto extent() const -> QgsRectangle pure virtual
Returns the extent of the layer.
auto fileRasterFilters() const -> QString virtual
Returns raster file filter string.
auto fileVectorFilters() const -> QString virtual
Returns vector file filter string.
void invalidateConnections(const QString& connection) virtual
Invalidate connections corresponding to specified name.
auto isValid() const -> bool pure virtual
Returns true if this is a valid layer.
auto layerMetadata() const -> QgsLayerMetadata virtual
Returns layer metadata collected from the provider's source.
auto leaveUpdateMode() -> bool virtual
Leave update mode.
auto name() const -> QString pure virtual
Returns a provider name.
auto providerProperty(ProviderProperty property, const QVariant& defaultValue = QVariant()) const -> QVariant
Gets the current value of a certain provider property.
auto providerProperty(int property, const QVariant& defaultValue) const -> QVariant
Gets the current value of a certain provider property.
void reloadData() virtual
Reloads the data from the source.
auto renderInPreview(const QgsDataProvider::PreviewContext& context) -> bool virtual
Returns whether the layer must be rendered in preview jobs.
void setDataSourceUri(const QString& uri) virtual
Set the data source specification.
void setLayerOrder(const QStringList& layers) virtual
Reorder the list of layer names to be rendered by this provider (in order from bottom to top)
void setListening(bool isListening) virtual
Set whether the provider will listen to datasource notifications If set, the provider will issue notify signals.
void setProviderProperty(ProviderProperty property, const QVariant& value)
Allows setting arbitrary properties on the provider.
void setProviderProperty(int property, const QVariant& value)
Allows setting arbitrary properties on the provider.
void setSubLayerVisibility(const QString& name, bool vis) virtual
Set the visibility of the given sublayer name.
auto setSubsetString(const QString& subset, bool updateFeatureCount = true) -> bool virtual
Set the subset string used to create a subset of features in the layer.
void setUri(const QgsDataSourceUri& uri)
Set the data source specification.
auto subLayerCount() const -> uint virtual
Returns the number of layers for the current data source.
auto subLayers() const -> QStringList virtual
Sub-layers handled by this provider, in order from bottom to top.
auto subLayerStyles() const -> QStringList virtual
Sub-layer styles for each sub-layer handled by this provider, in order from bottom to top.
auto subsetString() const -> QString virtual
Returns the subset definition string (typically sql) currently in use by the layer and used by the provider to limit the feature set.
auto supportsSubsetString() const -> bool virtual
Returns true if the provider supports setting of subset strings.
auto timestamp() const -> QDateTime virtual
Time stamp of data source in the moment when data/metadata were loaded by provider.
void updateExtents() virtual
Update the extents of the layer.
auto uri() const -> QgsDataSourceUri
Gets the data source specification.
auto writeLayerMetadata(const QgsLayerMetadata& metadata) -> bool virtual
Writes layer metadata to the underlying provider source.

Signals

void dataChanged()
Emitted whenever a change is made to the data provider which may have caused changes in the provider's data OUTSIDE of QGIS.
void fullExtentCalculated()
Emitted whenever a deferred extent calculation is completed by the provider.
void notify(const QString& msg)
Emitted when the datasource issues a notification.

Protected functions

void appendError(const QgsErrorMessage& message)
Add error message.
void setError(const QgsError& error)
Sets error message.

Protected variables

QgsError mError
Error.
QDateTime mTimestamp
Timestamp of data in the moment when the data were loaded by provider.

Enum documentation

enum QgsDataProvider::ProviderProperty

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.

Enumerators
EvaluateDefaultValues

Evaluate default values on provider side when calling QgsVectorDataProvider::defaultValue( int index ) rather than on commit.
CustomData

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.

Function documentation

QgsDataProvider::QgsDataProvider(const QString& uri = QString(), const QgsDataProvider::ProviderOptions& options = QgsDataProvider::ProviderOptions())

Create a new dataprovider with the specified in the uri.

Additional creation options are specified within the options value.

QgsCoordinateReferenceSystem QgsDataProvider::crs() const pure virtual

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.

QString QgsDataProvider::dataSourceUri(bool expandAuthConfig = false) const virtual

Gets the data source specification.

Parameters
expandAuthConfig Whether to expand any assigned authentication configuration
Returns data source specification

This may be a path or database connection string

QString QgsDataProvider::description() const pure virtual

Returns description.

Returns a terse string describing what the provider is.

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?

bool QgsDataProvider::enterUpdateMode() virtual

Enter update mode.

Returns true in case of success (or no-op implementation), false in case of failure.

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.

QgsError QgsDataProvider::error() const virtual

Gets 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.

QgsRectangle QgsDataProvider::extent() const pure virtual

Returns the extent of the layer.

Returns QgsRectangle containing the extent of the layer

QString QgsDataProvider::fileRasterFilters() const virtual

Returns 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.

QString QgsDataProvider::fileVectorFilters() const virtual

Returns 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.

void QgsDataProvider::invalidateConnections(const QString& connection) virtual

Invalidate connections corresponding to specified name.

bool QgsDataProvider::isValid() const pure virtual

Returns true if this is a valid layer.

It is up to individual providers to determine what constitutes a valid layer.

QgsLayerMetadata QgsDataProvider::layerMetadata() const virtual

Returns layer metadata collected from the provider's source.

Individual data providers must implement this method if they support collecting metadata.

bool QgsDataProvider::leaveUpdateMode() virtual

Leave update mode.

Returns true in case of success (or no-op implementation), false in case of failure.

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.

QString QgsDataProvider::name() const pure virtual

Returns 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.

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?

QVariant QgsDataProvider::providerProperty(ProviderProperty property, const QVariant& defaultValue = QVariant()) const

Gets the current value of a certain provider property.

It depends on the provider which properties are supported.

QVariant QgsDataProvider::providerProperty(int property, const QVariant& defaultValue) const

Gets the current value of a certain provider property.

It depends on the provider which properties are supported.

void QgsDataProvider::reloadData() virtual

Reloads the data from the source.

Needs to be implemented by providers with data caches to synchronize with changes in the data source

bool QgsDataProvider::renderInPreview(const QgsDataProvider::PreviewContext& context) virtual

Returns whether the layer must be rendered in preview jobs.

The context argument gives useful information which can be used to determine whether the layer should be rendered or not.

The base implementation returns true if lastRenderingTimeMs <= maxRenderingTimeMs.

void QgsDataProvider::setDataSourceUri(const QString& uri) virtual

Set the data source specification.

Parameters
uri source specification

This may be a path or database connection string

void QgsDataProvider::setLayerOrder(const QStringList& layers) virtual

Reorder the list of layer names to be rendered by this provider (in order from bottom to top)

void QgsDataProvider::setListening(bool isListening) virtual

Set whether the provider will listen to datasource notifications If set, the provider will issue notify signals.

The default implementation does nothing.

void QgsDataProvider::setProviderProperty(ProviderProperty property, const QVariant& value)

Allows setting arbitrary properties on the provider.

It depends on the provider which properties are supported.

void QgsDataProvider::setProviderProperty(int property, const QVariant& value)

Allows setting arbitrary properties on the provider.

It depends on the provider which properties are supported.

bool QgsDataProvider::setSubsetString(const QString& subset, bool updateFeatureCount = true) virtual

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.

void QgsDataProvider::setUri(const QgsDataSourceUri& uri)

Set the data source specification.

QStringList QgsDataProvider::subLayers() const virtual

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.

QStringList QgsDataProvider::subLayerStyles() const virtual

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.

QString QgsDataProvider::subsetString() const virtual

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.

void QgsDataProvider::updateExtents() virtual

Update the extents of the layer.

Not implemented by default.

QgsDataSourceUri QgsDataProvider::uri() const

Gets the data source specification.

bool QgsDataProvider::writeLayerMetadata(const QgsLayerMetadata& metadata) virtual

Writes layer metadata to the underlying provider source.

Support depends on individual provider capabilities.

Returns true if metadata was successfully written to the data provider.

void QgsDataProvider::dataChanged() signal

Emitted whenever a change is made to the data provider which may have caused changes in the provider's data OUTSIDE of QGIS.

When emitted from a QgsVectorDataProvider, any cached information such as feature ids should be invalidated.

void QgsDataProvider::fullExtentCalculated() signal

Emitted whenever a deferred extent calculation is completed by the provider.

Layers should connect to this signal and update their cached extents whenever it is emitted.

void QgsDataProvider::notify(const QString& msg) signal

Emitted when the datasource issues a notification.

Variable documentation

static QString QgsDataProvider::SUBLAYER_SEPARATOR

String sequence used for separating components of sublayers strings.