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









class QgsMeshDriverMetadata
{
%Docstring(signature="appended")
Holds metadata about mesh driver

.. versionadded:: 3.12
%End

%TypeHeaderCode
#include "qgsprovidermetadata.h"
%End
  public:
    static const QMetaObject staticMetaObject;

  public:

    enum MeshDriverCapability /BaseType=IntEnum/
    {
      CanWriteFaceDatasets,
      CanWriteVertexDatasets,
      CanWriteEdgeDatasets,
      CanWriteMeshData,
    };

    typedef QFlags<QgsMeshDriverMetadata::MeshDriverCapability> MeshDriverCapabilities;


    QgsMeshDriverMetadata();
%Docstring
Constructs default metadata without any capabilities
%End

 QgsMeshDriverMetadata( const QString &name,
        const QString &description,
        const MeshDriverCapabilities &capabilities,
        const QString &writeDatasetOnFileSuffix ) /Deprecated/;
%Docstring
Constructs driver metadata with selected capabilities

:param name: name/key of the driver
:param description: short description of the driver
:param capabilities: driver's capabilities
:param writeDatasetOnFileSuffix: suffix used to write datasets on file

.. deprecated:: 3.22
%End

    QgsMeshDriverMetadata( const QString &name,
                           const QString &description,
                           const MeshDriverCapabilities &capabilities,
                           const QString &writeDatasetOnFileSuffix,
                           const QString &writeMeshFrameOnFileSuffix,
                           int maxVerticesPerface );
%Docstring
Constructs driver metadata with selected capabilities

:param name: name/key of the driver
:param description: short description of the driver
:param capabilities: driver's capabilities
:param writeDatasetOnFileSuffix: suffix used to write datasets on file
:param writeMeshFrameOnFileSuffix: suffix used to write mesh frame on
                                   file
:param maxVerticesPerface: maximum vertices count per face supported by
                           the driver

.. versionadded:: 3.22
%End

    MeshDriverCapabilities capabilities() const;
%Docstring
Returns the capabilities for this driver.
%End

    QString name() const;
%Docstring
Returns the name (key) for this driver.
%End

    QString description() const;
%Docstring
Returns the description for this driver.
%End

    QString writeDatasetOnFileSuffix() const;
%Docstring
Returns the suffix used to write datasets on file
%End

    QString writeMeshFrameOnFileSuffix() const;
%Docstring
Returns the suffix used to write mesh on file

.. versionadded:: 3.22
%End

    int maximumVerticesCountPerFace() const;
%Docstring
Returns the maximum number of vertices per face supported by the driver

.. versionadded:: 3.22
%End

};

QFlags<QgsMeshDriverMetadata::MeshDriverCapability> operator|(QgsMeshDriverMetadata::MeshDriverCapability f1, QFlags<QgsMeshDriverMetadata::MeshDriverCapability> f2);


class QgsProviderMetadata : QObject
{
%Docstring(signature="appended")
Holds data provider key, description, and associated shared library file
or function pointer information.

Provider metadata refers either to providers which are loaded via
libraries or which are native providers that are included in the core
QGIS installation and accessed through function pointers.

For library based providers, the metadata class is used in a lazy load
implementation in :py:class:`QgsProviderRegistry`. To save memory, data
providers are only actually loaded via QLibrary calls if they're to be
used. (Though they're all iteratively loaded once to get their metadata
information, and then unloaded when the :py:class:`QgsProviderRegistry`
is created.) :py:class:`QgsProviderMetadata` supplies enough information
to be able to later load the associated shared library object.
%End

%TypeHeaderCode
#include "qgsprovidermetadata.h"
%End
  public:

    enum ProviderMetadataCapability /BaseType=IntEnum/
    {
      PriorityForUri,
      LayerTypesForUri,
      QuerySublayers,
      CreateDatabase,
    };
    typedef QFlags<QgsProviderMetadata::ProviderMetadataCapability> ProviderMetadataCapabilities;


    enum ProviderCapability /BaseType=IntEnum/
    {
      FileBasedUris,
      SaveLayerMetadata,
      ParallelCreateProvider,
    };
    typedef QFlags<QgsProviderMetadata::ProviderCapability> ProviderCapabilities;



    QgsProviderMetadata( const QString &key, const QString &description, const QString &library = QString() );
%Docstring
Constructor for provider metadata

:param key: provider key
:param description: provider description
:param library: plugin library file name (empty if the provider is not
                loaded from a library)
%End


    virtual ~QgsProviderMetadata();

    QString key() const;
%Docstring
This returns the unique key associated with the provider

This key string is used for the associative container in
:py:class:`QgsProviderRegistry`
%End

    QString description() const;
%Docstring
This returns descriptive text for the provider

This is used to provide a descriptive list of available data providers.
%End

    virtual QIcon icon() const;
%Docstring
Returns an icon representing the provider.

.. versionadded:: 3.26
%End

    virtual QgsProviderMetadata::ProviderMetadataCapabilities capabilities() const;
%Docstring
Returns the provider metadata capabilities.

.. versionadded:: 3.18
%End

    virtual QgsProviderMetadata::ProviderCapabilities providerCapabilities() const;
%Docstring
Returns the provider's capabilities.

.. versionadded:: 3.18.1
%End

    SIP_PYOBJECT supportedLayerTypes() const /TypeHint="List[Qgis.LayerType]"/;
%Docstring
Returns a list of the map layer types supported by the provider.

.. versionadded:: 3.26
%End
%MethodCode
    // adapted from the qpymultimedia_qlist.sip file from the PyQt6 sources

    const QList< Qgis::LayerType > cppRes = sipCpp->supportedLayerTypes();

    PyObject *l = PyList_New( cppRes.size() );

    if ( !l )
      sipIsErr = 1;
    else
    {
      for ( int i = 0; i < cppRes.size(); ++i )
      {
        PyObject *eobj = sipConvertFromEnum( static_cast<int>( cppRes.at( i ) ),
                                             sipType_Qgis_LayerType );

        if ( !eobj )
        {
          sipIsErr = 1;
        }

        PyList_SetItem( l, i, eobj );
      }

      if ( !sipIsErr )
      {
        sipRes = l;
      }
      else
      {
        Py_DECREF( l );
      }
    }
%End

 QString library() const /Deprecated/;
%Docstring
This returns the library file name

This is used to QLibrary calls to load the data provider (only for
dynamically loaded libraries)

.. deprecated:: 3.10

   Providers may not need to be loaded from a library (empty string returned).
%End


    virtual void initProvider();
%Docstring
Initialize the provider

.. versionadded:: 3.10
%End

    virtual void cleanupProvider();
%Docstring
Cleanup the provider

.. versionadded:: 3.10
%End

    virtual QString filters( Qgis::FileFilterType type );
%Docstring
Builds the list of file filter strings (supported formats)

Suitable for use in a QFileDialog.getOpenFileNames() call.

.. versionadded:: 3.10
%End

    virtual QList<QgsMeshDriverMetadata> meshDriversMetadata();
%Docstring
Builds the list of available mesh drivers metadata

.. versionadded:: 3.12
%End

    virtual int priorityForUri( const QString &uri ) const;
%Docstring
Returns an integer representing the priority which this provider should
have when opening a dataset with the specified ``uri``.

A larger priority means that the provider should be selected over others
with a lower priority for the same URI.

The default implementation returns 0 for all URIs.

.. warning::

   Not all providers implement this functionality. Check whether :py:func:`~QgsProviderMetadata.capabilities` returns the
   ProviderMetadataCapability.PriorityForUri to determine whether a specific provider metadata object
   supports this method.

.. versionadded:: 3.18
%End

    virtual QList< Qgis::LayerType > validLayerTypesForUri( const QString &uri ) const;
%Docstring
Returns a list of valid layer types which the provider can be used with
when opening the specified ``uri``.

.. warning::

   Not all providers implement this functionality. Check whether :py:func:`~QgsProviderMetadata.capabilities` returns the
   ProviderMetadataCapability.LayerTypesForUri to determine whether a specific provider metadata object
   supports this method.

.. versionadded:: 3.18
%End

    virtual bool uriIsBlocklisted( const QString &uri ) const;
%Docstring
Returns ``True`` if the specified ``uri`` is known by this provider to
be something which should be blocklisted from the QGIS interface, e.g.
an internal detail only.

Specifically, this method can be utilized by the browser panel to hide
noisy internal details by returning ``True`` for URIs which are known to
be sidecar files only, such as ".aux.xml" files or ".shp.xml" files, or
the "ept-build.json" files which sit alongside Entwine "ept.json" point
cloud sources.

The default method returns ``False`` for all URIs.

.. warning::

   Returning ``True`` from an implementation of this method indicates that ALL providers should
   ignore the specified ``uri``, not just the provider associated with this metadata!

.. versionadded:: 3.18
%End

    virtual QStringList sidecarFilesForUri( const QString &uri ) const;
%Docstring
Given a ``uri``, returns any sidecar files which are associated with the
URI and this provider.

In this context a sidecar file is defined as a file which shares the
same base filename as a dataset, but which differs in file extension. It
defines the list of additional files which must be renamed or deleted
alongside the main file associated with the dataset in order to
completely rename/delete the dataset.

For instance, the OGR provider would return the corresponding .dbf,
.idx, etc files for a uri pointing at a .shp file.

Implementations should files any files which MAY exist for the URI, and
it is up to the caller to filter these to only existing files if
required.

.. note::

   Some file formats consist of a set of static file names, such as ESRI aigrid datasets
   which consist of a folder with files with the names "hdr.adf", "prj.adf", etc. These statically
   named files are NOT considered as sidecar files.

.. versionadded:: 3.22
%End

    virtual QList< QgsProviderSublayerDetails > querySublayers( const QString &uri, Qgis::SublayerQueryFlags flags = Qgis::SublayerQueryFlags(), QgsFeedback *feedback = 0 ) const;
%Docstring
Queries the specified ``uri`` and returns a list of any valid sublayers
found in the dataset which can be handled by this provider.

The optional ``flags`` argument can be used to control the behavior of
the query.

The optional ``feedback`` argument can be used to provide cancellation
support for long-running queries.

.. note::

   Providers which implement this method should always return a list of sublayer details for any valid, even if the ``uri``
   only relates to a single layer. Returning a non-empty list indicates that the provider is able to load at least one layer using the ``uri``,
   and is used to collate a combined layer of all providers which support the URI (e.g. in the case that a URI may be readable by multiple
   different providers).

.. versionadded:: 3.22
%End

    virtual QString suggestGroupNameForUri( const QString &uri ) const;
%Docstring
Returns a name that can be used as a group name for sublayers retrieved
from the specified ``uri``.

The default implementation returns an empty string.

.. versionadded:: 3.30
%End

    virtual QgsDataProvider *createProvider( const QString &uri,
        const QgsDataProvider::ProviderOptions &options,
        Qgis::DataProviderReadFlags flags = Qgis::DataProviderReadFlags() ) /Factory/;
%Docstring
Class factory to return a pointer to a newly created
:py:class:`QgsDataProvider` object

:param uri: the datasource uri
:param options: creation options
:param flags: creation flags, sing QGIS 3.16

.. versionadded:: 3.10
%End

    static void setBoolParameter( QVariantMap &uri, const QString &parameter, const QVariant &value );
%Docstring
Sets the ``value`` into the ``uri`` ``parameter`` as a bool. eg. "yes"
value will be saved as ``True``, 0 will be saved as ``False``

.. versionadded:: 3.14
%End

    static bool boolParameter( const QVariantMap &uri, const QString &parameter, bool defaultValue = false );
%Docstring
Returns the ``parameter`` value in the ``uri`` as a bool. eg. "yes"
value will be returned as ``True``, 0 will be returned as ``False``

.. versionadded:: 3.14
%End



    virtual bool createDatabase( const QString &uri, QString &errorMessage /Out/ );
%Docstring
Creates a new empty database at the specified ``uri``.

This method can be used for supported providers to construct a new empty
database. For instance, the OGR provider metadata
:py:func:`~QgsProviderMetadata.createDatabase` method can be used to
create new empty GeoPackage or FileGeodatabase databases.

:param uri: destination URI for newly created database.

:return: - ``True`` if the database was successfully created
         - errorMessage: a descriptive error message if the database
           could not be successfully created.

.. note::

   This method is only supported by providers which return the QgsProviderMetadata.ProviderMetadataCapability.CreateDatabase capability.

.. versionadded:: 3.28
%End

    virtual QgsRasterDataProvider *createRasterDataProvider(
      const QString &uri,
      const QString &format,
      int nBands,
      Qgis::DataType type,
      int width,
      int height,
      double *geoTransform,
      const QgsCoordinateReferenceSystem &crs,
      const QStringList &createOptions = QStringList() ) /Factory/;
%Docstring
Creates a new instance of the raster data provider.

.. versionadded:: 3.10
%End

    virtual bool createMeshData(
      const QgsMesh &mesh,
      const QString &fileName,
      const QString &driverName,
      const QgsCoordinateReferenceSystem &crs,
      const QMap<QString, QString> &metadata = QMap<QString, QString>() ) const;
%Docstring
Creates mesh data source from a file name ``fileName`` and a driver
``driverName``, that is the mesh frame stored in file, memory or with
other way (depending of the provider) Since QGIS 3.38 the optional
``metadata`` argument can be used to pass metadata to the provider.

.. versionadded:: 3.16
%End

    virtual bool createMeshData(
      const QgsMesh &mesh,
      const QString &uri,
      const QgsCoordinateReferenceSystem &crs,
      const QMap<QString, QString> &metadata = QMap<QString, QString>() ) const;
%Docstring
Creates mesh data source from an ``uri``, that is the mesh frame stored
in file, memory or with other way (depending of the provider) Since QGIS
3.38 the optional ``metadata`` argument can be used to pass metadata to
the provider.

.. versionadded:: 3.22
%End

    virtual QList<QPair<QString, QString> > pyramidResamplingMethods();
%Docstring
Returns pyramid resampling methods available for provider

.. versionadded:: 3.10
%End

    virtual QVariantMap decodeUri( const QString &uri ) const;
%Docstring
Breaks a provider data source URI into its component paths (e.g. file
path, layer name).

:param uri: uri string

:return: map containing components. Standard components may include:

         - "path": file path
         - "layerName"
         - "url": base URL, for online services
         - "referer": referrer string, for HTTP requests
         - "host": hostname, for database services
         - "bounds": hardcoded layer bounds (as a :py:class:`QgsRectangle`)
         - "crs": CRS definition
         - "authcfg": authentication configuration ID

.. note::

   this function may not be supported by all providers, an empty map will be returned in such case

.. versionadded:: 3.10
%End

    virtual QString encodeUri( const QVariantMap &parts ) const;
%Docstring
Reassembles a provider data source URI from its component paths (e.g.
file path, layer name).

:param parts: parts as returned by decodeUri

:return: datasource uri string

.. note::

   this function may not be supported by all providers, an empty string will be returned in such case

.. seealso:: :py:func:`decodeUri`

.. versionadded:: 3.12
%End

    virtual QString absoluteToRelativeUri( const QString &uri, const QgsReadWriteContext &context ) const;
%Docstring
Converts absolute path(s) to relative path(s) in the given
provider-specific URI. and returns modified URI according to the context
object's configuration. This is commonly used when writing project
files. If a provider does not work with paths, unmodified URI will be
returned.

:return: modified URI with relative path(s)

.. note::

   this function may not be supported by all providers. The default
   implementation uses :py:func:`QgsPathResolver.writePath()` on the whole URI.

.. seealso:: :py:func:`relativeToAbsoluteUri`

.. versionadded:: 3.30
%End

    virtual QString relativeToAbsoluteUri( const QString &uri, const QgsReadWriteContext &context ) const;
%Docstring
Converts relative path(s) to absolute path(s) in the given
provider-specific URI. and returns modified URI according to the context
object's configuration. This is commonly used when reading project
files. If a provider does not work with paths, unmodified URI will be
returned.

:return: modified URI with absolute path(s)

.. note::

   this function may not be supported by all providers. The default
   implementation uses :py:func:`QgsPathResolver.readPath()` on the whole URI.

.. seealso:: :py:func:`absoluteToRelativeUri`

.. versionadded:: 3.30
%End

    virtual QString cleanUri( const QString &uri, Qgis::UriCleaningFlags flags = Qgis::UriCleaningFlag::RemoveCredentials ) const;
%Docstring
Cleans a layer ``uri``, e.g. to remove or hide sensitive information
from the URI.

.. versionadded:: 3.42
%End

    virtual QList< QgsDataItemProvider * > dataItemProviders() const /Factory/;
%Docstring
Returns data item providers. Caller is responsible for ownership of the
item providers

.. seealso:: :py:func:`QgsProviderGuiMetadata.dataItemGuiProviders`

.. note::

   Ownership of created data item providers is passed to the caller.

.. versionadded:: 3.10
%End

    virtual int listStyles( const QString &uri, QStringList &ids, QStringList &names,
                            QStringList &descriptions, QString &errCause );
%Docstring
Lists stored layer styles in the provider defined by ``uri``

:return: - 1 if not implemented by provider, otherwise number of styles
           stored

.. versionadded:: 3.10
%End

    virtual bool styleExists( const QString &uri, const QString &styleId, QString &errorCause /Out/ );
%Docstring
Returns ``True`` if a layer style with the specified ``styleId`` exists
in the provider defined by ``uri``.

:param uri: provider URI
:param styleId: style ID to test for

:return: - ``True`` if the layer style already exists
         - errorCause: a descriptive error message, if an error occurs
           while checking if the style exists

.. seealso:: :py:func:`getStyleById`

.. versionadded:: 3.24
%End

    virtual QString getStyleById( const QString &uri, const QString &styleId, QString &errCause );
%Docstring
Gets a layer style defined by ``uri``

.. seealso:: :py:func:`styleExists`

.. versionadded:: 3.10
%End

    virtual bool deleteStyleById( const QString &uri, const QString &styleId, QString &errCause );
%Docstring
Deletes a layer style defined by ``styleId``

.. versionadded:: 3.10
%End

    virtual bool saveStyle( const QString &uri, const QString &qmlStyle, const QString &sldStyle,
                            const QString &styleName, const QString &styleDescription,
                            const QString &uiFileContent, bool useAsDefault, QString &errCause );
%Docstring
Saves a layer style to provider.

.. note::

   Prior to QGIS 3.24, this method would show a message box warning when a
   style with the same ``styleName`` already existed to confirm replacing the style with the user.
   Since 3.24, calling this method will ALWAYS overwrite any existing style with the same name.
   Use :py:func:`~QgsProviderMetadata.styleExists` to test in advance if a style already exists and handle this appropriately
   in your client code.

.. versionadded:: 3.10
%End

    virtual QString loadStyle( const QString &uri, QString &errCause );
%Docstring
Loads a layer style defined by ``uri``

.. versionadded:: 3.10
%End

    virtual QString loadStoredStyle( const QString &uri, QString &styleName, QString &errCause );
%Docstring
Loads a layer style from the provider storage, reporting its name.

:param uri: data source uri
:param styleName: the name of the style if available, empty otherwise
:param errCause: report errors

:return: the style QML (XML)

.. versionadded:: 3.30
%End

    virtual bool saveLayerMetadata( const QString &uri, const QgsLayerMetadata &metadata, QString &errorMessage /Out/ ) throw( QgsNotSupportedException );
%Docstring
Saves ``metadata`` to the layer corresponding to the specified ``uri``.

:param uri: uri of layer to store metadata for
:param metadata: layer metadata

:return: - ``True`` if the metadata was successfully saved.
         - errorMessage: descriptive string of error if encountered

:raises QgsNotSupportedException: if the provider does not support
                                  saving layer metadata for the
                                  specified ``uri``.

.. versionadded:: 3.20
%End

    virtual bool createDb( const QString &dbPath, QString &errCause );
%Docstring
Creates database by the provider on the path

.. versionadded:: 3.10
%End

    virtual QgsTransaction *createTransaction( const QString &connString ) /Factory/;
%Docstring
Returns new instance of transaction. Ownership is transferred to the
caller

.. versionadded:: 3.10
%End

    virtual QMap<QString, QgsAbstractProviderConnection *> connections( bool cached = true ) throw( QgsProviderConnectionException );
%Docstring
Returns a dictionary of stored provider connections, the dictionary key
is the connection identifier. Ownership is not transferred. Raises a
:py:class:`QgsProviderConnectionException` if any errors are
encountered.

:param cached: if ``False`` connections will be re-read from the
               settings

:raises QgsProviderConnectionException: 

.. versionadded:: 3.10
%End

    QMap<QString, QgsAbstractDatabaseProviderConnection *> dbConnections( bool cached = true ) throw( QgsProviderConnectionException );
%Docstring
Returns a dictionary of database provider connections, the dictionary
key is the connection identifier. Ownership is not transferred. Raises a
:py:class:`QgsProviderConnectionException` if any errors are
encountered.

:param cached: if ``False`` connections will be re-read from the
               settings

:raises QgsProviderConnectionException: 

.. versionadded:: 3.10
%End

    QgsAbstractProviderConnection *findConnection( const QString &name, bool cached = true ) throw( QgsProviderConnectionException );
%Docstring
Searches and returns a (possibly ``None``) connection from the stored
provider connections. Ownership is not transferred. Raises a
:py:class:`QgsProviderConnectionException` if any errors are
encountered.

:param name: the connection name
:param cached: if ``False`` connections will be re-read from the
               settings

:raises QgsProviderConnectionException: 

.. versionadded:: 3.10
%End


    virtual QgsAbstractProviderConnection *createConnection( const QString &uri, const QVariantMap &configuration ) throw( QgsProviderConnectionException ) /Factory/;
%Docstring
Creates a new connection from ``uri`` and ``configuration``, the newly
created connection is not automatically stored in the settings, call
:py:func:`~QgsProviderMetadata.saveConnection` to save it. Ownership is
transferred to the caller.

:raises QgsProviderConnectionException: 

.. seealso:: :py:func:`saveConnection`

.. versionadded:: 3.10
%End

    virtual QgsAbstractProviderConnection *createConnection( const QString &name ) throw( QgsProviderConnectionException ) /Factory/;
%Docstring
Creates a new connection by loading the connection with the given
``name`` from the settings. Ownership is transferred to the caller.

:raises QgsProviderConnectionException: 

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

    virtual void deleteConnection( const QString &name ) throw( QgsProviderConnectionException );
%Docstring
Removes the connection with the given ``name`` from the settings. Raises
a :py:class:`QgsProviderConnectionException` if any errors are
encountered.

:raises QgsProviderConnectionException: 

.. versionadded:: 3.10
%End

    virtual void saveConnection( const QgsAbstractProviderConnection *connection, const QString &name ) throw( QgsProviderConnectionException );
%Docstring
Stores the connection in the settings

:param connection: the connection to be stored in the settings
:param name: the name under which the connection will be stored

:raises QgsProviderConnectionException: 

.. versionadded:: 3.10
%End

    SIP_PYOBJECT __repr__();
%MethodCode
    QString str = QStringLiteral( "<QgsProviderMetadata: %1>" ).arg( sipCpp->key() );
    sipRes = PyUnicode_FromString( str.toUtf8().constData() );
%End

  signals:

    void connectionCreated( const QString &name );
%Docstring
Emitted when a connection with the specified ``name`` is created.

.. note::

   Only providers which implement the connection handling API will emit this signal.

.. versionadded:: 3.14
%End

    void connectionDeleted( const QString &name );
%Docstring
Emitted when the connection with the specified ``name`` was deleted.

.. note::

   Only providers which implement the connection handling API will emit this signal.

.. versionadded:: 3.14
%End

    void connectionChanged( const QString &name );
%Docstring
Emitted when the connection with the specified ``name`` is changed, e.g.
the settings relating to the connection have been updated.

.. note::

   Only providers which implement the connection handling API will emit this signal.

.. versionadded:: 3.14
%End

  protected:


};

QFlags<QgsProviderMetadata::ProviderMetadataCapability> operator|(QgsProviderMetadata::ProviderMetadataCapability f1, QFlags<QgsProviderMetadata::ProviderMetadataCapability> f2);

QFlags<QgsProviderMetadata::ProviderCapability> operator|(QgsProviderMetadata::ProviderCapability f1, QFlags<QgsProviderMetadata::ProviderCapability> f2);


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