/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/providers/qgsdataprovider.h                                 *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/






class QgsDataProvider : QObject
{
%Docstring(signature="appended")
Abstract base class for spatial data provider implementations.
%End

%TypeHeaderCode
#include "qgsdataprovider.h"
%End
%ConvertToSubClassCode
    if ( qobject_cast<QgsVectorDataProvider *>( sipCpp ) )
    {
      sipType = sipType_QgsVectorDataProvider;
    }
    else if ( qobject_cast<QgsRasterDataProvider *>( sipCpp ) )
    {
      sipType = sipType_QgsRasterDataProvider;
    }
    else if ( qobject_cast<QgsMeshDataProvider *>( sipCpp ) )
    {
      sipType = sipType_QgsMeshDataProvider;
    }
    else if ( qobject_cast<QgsPointCloudDataProvider *>( sipCpp ) )
    {
      sipType = sipType_QgsPointCloudDataProvider;
    }
    else
    {
      sipType = 0;
    }
%End
  public:

    enum ProviderProperty /BaseType=IntEnum/
    {
      EvaluateDefaultValues,
      CustomData
    };

    struct ProviderOptions
    {

      QgsCoordinateTransformContext transformContext;

    };

    QgsDataProvider( const QString &uri = QString(),
                     const QgsDataProvider::ProviderOptions &providerOptions = QgsDataProvider::ProviderOptions(),
                     Qgis::DataProviderReadFlags flags = Qgis::DataProviderReadFlags() );
%Docstring
Create a new dataprovider with the specified in the ``uri``.

Additional creation options are specified within the ``options`` value
and since QGIS 3.16 creation flags are specified within the ``flags``
value.
%End

    virtual QgsCoordinateReferenceSystem crs() const = 0;
%Docstring
Returns the coordinate system for the data source. If the provider isn't
capable of returning its projection then an invalid
:py:class:`QgsCoordinateReferenceSystem` will be returned.
%End

    virtual void setDataSourceUri( const QString &uri );
%Docstring
Set the data source specification. This may be a path or database
connection string

:param uri: source specification
%End

    virtual QString dataSourceUri( bool expandAuthConfig = false ) const;
%Docstring
Gets 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
%End

    virtual QString dataComment() const;
%Docstring
Returns a short comment for the data that this provider is providing
access to (e.g. the comment for postgres table).

.. note::

   The default implementation returns an empty string.

.. versionadded:: 3.14
%End
    virtual QString htmlMetadata() const;
%Docstring
Obtain a formatted HTML string containing assorted metadata for this
data provider.

.. versionadded:: 3.36
%End

    void setUri( const QgsDataSourceUri &uri );
%Docstring
Set the data source specification.
%End

    void setUri( const QString &uri );
%Docstring
Set the data source specification.

.. versionadded:: 3.38
%End

    QgsDataSourceUri uri() const;
%Docstring
Gets the data source specification.
%End

    virtual Qgis::DataProviderFlags flags() const;
%Docstring
Returns the generic data provider flags.

.. versionadded:: 3.26
%End

    virtual QgsDataProviderTemporalCapabilities *temporalCapabilities();
%Docstring
Returns the provider's temporal capabilities.

This may be ``None``, depending on the data provider.

.. versionadded:: 3.14
%End


    virtual QgsDataProviderElevationProperties *elevationProperties();
%Docstring
Returns the provider's elevation properties.

This may be ``None``, depending on the data provider.

.. versionadded:: 3.32
%End


    virtual QgsRectangle extent() const = 0;
%Docstring
Returns the extent of the layer.

.. warning::

   This may be expensive to calculate for some data providers, as it may involve
   additional network requests or in some cases, iterating through all the features in a layer.
   If the provider returns the :py:class:`Qgis`.DataProviderFlag.FastExtent2D flag from the :py:func:`~QgsDataProvider.flags` method
   then the call to :py:func:`~QgsDataProvider.extent` is guaranteed to ALWAYS be fast and not involve any additional work.
%End

    virtual QgsBox3D extent3D() const;
%Docstring
Returns the 3D extent of the layer.

.. warning::

   This may be expensive to calculate for some data providers, as it may involve
   additional network requests or in some cases, iterating through all the features in a layer.
   If the provider returns the :py:class:`Qgis`.DataProviderFlag.FastExtent3D flag from the :py:func:`~QgsDataProvider.flags` method
   then the call to :py:func:`~QgsDataProvider.extent3D` is guaranteed to ALWAYS be fast and not involve any additional work.

.. versionadded:: 3.36
%End

    virtual bool isValid() const = 0;
%Docstring
Returns ``True`` if this is a valid layer. It is up to individual
providers to determine what constitutes a valid layer.
%End

    virtual void updateExtents();
%Docstring
Update the extents of the layer. Not implemented by default.
%End

    virtual QString subsetStringDialect() const;
%Docstring
Returns a user-friendly string describing the dialect which is supported
for subset strings by the provider.

.. seealso:: :py:func:`subsetStringHelpUrl`

.. seealso:: :py:func:`supportsSubsetString`

.. seealso:: :py:func:`setSubsetString`

.. seealso:: :py:func:`subsetString`

.. versionadded:: 3.40
%End

    virtual QString subsetStringHelpUrl() const;
%Docstring
Returns a URL pointing to documentation describing the dialect which is
supported for subset strings by the provider.

.. seealso:: :py:func:`subsetStringDialect`

.. seealso:: :py:func:`supportsSubsetString`

.. seealso:: :py:func:`setSubsetString`

.. seealso:: :py:func:`subsetString`

.. versionadded:: 3.40
%End

    virtual bool setSubsetString( const QString &subset, bool updateFeatureCount = true );
%Docstring
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. See
:py:func:`~QgsDataProvider.subsetStringDialect` and
:py:func:`~QgsDataProvider.subsetStringHelpUrl` for additional metadata
on the dialect supported by the subset string.

Must be implemented in the data provider.

.. seealso:: :py:func:`subsetString`

.. seealso:: :py:func:`subsetStringDialect`

.. seealso:: :py:func:`subsetStringHelpUrl`

.. seealso:: :py:func:`supportsSubsetString`
%End

    virtual bool supportsSubsetString() const;
%Docstring
Returns ``True`` if the provider supports setting of subset strings.

.. seealso:: :py:func:`subsetString`

.. seealso:: :py:func:`setSubsetString`
%End

    virtual QString subsetString() const;
%Docstring
Returns the subset definition string currently in use by the layer and
used by the provider to limit the feature set.

This may be a SQL where clause, or any other string that can be used by
the data provider to create a subset. See
:py:func:`~QgsDataProvider.subsetStringDialect` and
:py:func:`~QgsDataProvider.subsetStringHelpUrl` for additional metadata
on the dialect supported by the subset string.

Must be overridden in the data provider, otherwise returns an empty
string.

.. seealso:: :py:func:`setSubsetString`

.. seealso:: :py:func:`subsetStringDialect`

.. seealso:: :py:func:`subsetStringHelpUrl`

.. seealso:: :py:func:`supportsSubsetString`
%End

    virtual QStringList subLayers() const;
%Docstring
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.

.. seealso:: SUBLAYER_SEPARATOR
%End

    virtual QStringList subLayerStyles() const;
%Docstring
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.
%End


    virtual uint subLayerCount() const;
%Docstring
Returns the number of layers for the current data source
%End


    virtual void setLayerOrder( const QStringList &layers );
%Docstring
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.
%End


    virtual void setSubLayerVisibility( const QString &name, bool vis );
%Docstring
Set the visibility of the given sublayer name
%End



    virtual QString name() const = 0;
%Docstring
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.
%End


    virtual QString description() const = 0;
%Docstring
Returns description

Returns a terse string describing what the provider is.
%End


    virtual QString fileVectorFilters() const;
%Docstring
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.
%End


    virtual QString fileRasterFilters() const;
%Docstring
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.
%End


    virtual void reloadData();
%Docstring
Reloads the data from the source for providers with data caches to
synchronize, changes in the data source, feature counts and other
specific actions. Emits the `dataChanged` signal

.. note::

   only available for providers which implement the :py:func:`~QgsDataProvider.reloadProviderData` method.
%End

    virtual QDateTime timestamp() const;
%Docstring
Time stamp of data source in the moment when data/metadata were loaded
by provider
%End

    virtual QDateTime dataTimestamp() const;
%Docstring
Current time stamp of data source
%End

    virtual QgsError error() const;
%Docstring
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 :py:func:`~QgsDataProvider.block`,
:py:func:`~QgsDataProvider.identify` etc.
%End

    virtual void invalidateConnections( const QString &connection );
%Docstring
Invalidate connections corresponding to specified name
%End

    virtual bool enterUpdateMode();
%Docstring
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
:py:func:`~QgsDataProvider.leaveUpdateMode`, if this method returns
``True``.

Most providers will have an empty implementation for that method.

For backward compatibility, providers that implement
:py:func:`~QgsDataProvider.enterUpdateMode` should still make sure to
allow editing operations to work even if
:py:func:`~QgsDataProvider.enterUpdateMode` is not explicitly called.

Several successive calls to :py:func:`~QgsDataProvider.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
:py:func:`~QgsDataProvider.enterUpdateMode` will really turn update mode
on.

:return: ``True`` in case of success (or no-op implementation),
         ``False`` in case of failure.
%End

    virtual bool leaveUpdateMode();
%Docstring
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
:py:func:`~QgsDataProvider.enterUpdateMode`.

Most providers will have an empty implementation for that method.

Several successive calls to :py:func:`~QgsDataProvider.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
:py:func:`~QgsDataProvider.leaveUpdateMode` will really turn update mode
off.

:return: ``True`` in case of success (or no-op implementation),
         ``False`` in case of failure.
%End

    void setProviderProperty( ProviderProperty property, const QVariant &value );
%Docstring
Allows setting arbitrary properties on the provider. It depends on the
provider which properties are supported.
%End

    QVariant providerProperty( ProviderProperty property, const QVariant &defaultValue = QVariant() ) const;
%Docstring
Gets the current value of a certain provider property. It depends on the
provider which properties are supported.
%End

    virtual void setListening( bool isListening );
%Docstring
Set whether the provider will listen to datasource notifications If set,
the provider will issue notify signals.

The default implementation does nothing.

.. seealso:: :py:func:`notify`
%End


    virtual QgsLayerMetadata layerMetadata() const;
%Docstring
Returns layer metadata collected from the provider's source.

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

.. seealso:: :py:func:`writeLayerMetadata`
%End

    virtual bool writeLayerMetadata( const QgsLayerMetadata &metadata );
%Docstring
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.

.. seealso:: :py:func:`layerMetadata`
%End



    static QString sublayerSeparator();
%Docstring
String sequence used for separating components of sublayers strings.

.. note::

   Replaces the static const SUBLAYER_SEPARATOR

.. seealso:: :py:func:`subLayers`

.. versionadded:: 3.12
%End

    virtual Qgis::ProviderStyleStorageCapabilities styleStorageCapabilities() const;
%Docstring
Returns the style storage capabilities.

.. versionadded:: 3.34
%End

  signals:

    void fullExtentCalculated();
%Docstring
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.
%End

    void dataChanged();
%Docstring
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 :py:class:`QgsVectorDataProvider`, any cached
information such as feature ids should be invalidated.

.. warning::

   This signal is NOT emitted when changes are made to a provider
   from INSIDE QGIS -- e.g. when adding features to a vector layer, deleting features
   or modifying existing features. Instead, the specific :py:class:`QgsVectorLayer` signals
   should be used to detect these operations.
%End

    void notify( const QString &msg );
%Docstring
Emitted when the datasource issues a notification.

.. seealso:: :py:func:`setListening`
%End


  protected:



    void appendError( const QgsErrorMessage &message );
%Docstring
Add error message
%End

    void setError( const QgsError &error );
%Docstring
Sets error message
%End


};

/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/providers/qgsdataprovider.h                                 *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/