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





class QgsCredentials
{
%Docstring(signature="appended")
Interface for requesting credentials in QGIS in GUI independent way.

This class provides abstraction of a dialog for requesting credentials
to the user. By default :py:class:`QgsCredentials` will be used if not
overridden with other credential creator function.

QGIS application uses :py:class:`QgsCredentialDialog` class for
displaying a dialog to the user.

Caller can use the mutex to synchronize authentications to avoid
requesting credentials for the same resource several times.

Object deletes itself when it's not needed anymore. Children should use
signal :py:func:`~destroyed` to be notified of the deletion
%End

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

    virtual ~QgsCredentials();

    bool get( const QString &realm, QString &username /In,Out/, QString &password /In,Out/, const QString &message = QString(), bool requestCredentials = true );
%Docstring
Requests credentials for the specified ``realm``.

If existing credentials exist for the given ``realm``, these will be
returned. Otherwise the credential handler will prompt for the correct
username and password if ``requestCredentials`` is set to True.

The retrieved or user-entered details will be stored in ``username`` and
``password``.

Optionally, a specific ``message`` can be used to advise users of the
context for the credentials request.

.. note::

   This method will not automatically store the newly obtained credentials. Callers must
   manually call :py:func:`~QgsCredentials.put` after verifying that the obtained credentials are correct.

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

    void put( const QString &realm, const QString &username, const QString &password );
%Docstring
Stores the correct ``username`` and ``password`` for the specified
``realm``.

These values will be used for all future calls to
:py:func:`~QgsCredentials.get` for the same ``realm``, without
requesting users to re-enter them. It is the caller's responsibility to
ensure that only valid ``username`` and ``password`` combinations are
used with this method.

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

    bool getMasterPassword( QString &password /In,Out/, bool stored = false );

    static QgsCredentials *instance();
%Docstring
retrieves instance
%End

    void lock();
%Docstring
Lock the instance against access from multiple threads. This does not
really lock access to get/put methods, it will just prevent other
threads to lock the instance and continue the execution. When the class
is used from non-GUI threads, they should call
:py:func:`~QgsCredentials.lock` before the get/put calls to avoid race
conditions.
%End

    void unlock();
%Docstring
Unlock the instance after being locked.
%End

    QMutex *mutex();
%Docstring
Returns pointer to mutex
%End

  protected:

    QgsCredentials();

    virtual bool request( const QString &realm, QString &username /In,Out/, QString &password /In,Out/, const QString &message = QString() ) = 0;
%Docstring
request a password
%End

    virtual bool requestMasterPassword( QString &password /In,Out/, bool stored = false ) = 0;
%Docstring
request a master password
%End

    void setInstance( QgsCredentials *instance );
%Docstring
register instance
%End

  private:
    QgsCredentials( const QgsCredentials & );
};


class QgsCredentialsNone : QObject, QgsCredentials
{
%Docstring(signature="appended")
Default implementation of credentials interface

This class doesn't prompt or return credentials
%End

%TypeHeaderCode
#include "qgscredentials.h"
%End
  public:
    QgsCredentialsNone();

  signals:
    void destroyed();
%Docstring
signals that object will be destroyed and shouldn't be used anymore
%End

  protected:
    virtual bool request( const QString &realm, QString &username /In,Out/, QString &password /In,Out/, const QString &message = QString() );

    virtual bool requestMasterPassword( QString &password /In,Out/, bool stored = false );

};


class QgsCredentialsConsole : QObject, QgsCredentials
{
%Docstring(signature="appended")
Implementation of credentials interface for the console

This class outputs message to the standard output and retrieves input
from standard input. Therefore it won't be the right choice for apps
without GUI.
%End

%TypeHeaderCode
#include "qgscredentials.h"
%End
  public:
    QgsCredentialsConsole();

  signals:
    void destroyed();
%Docstring
signals that object will be destroyed and shouldn't be used anymore
%End

  protected:
    virtual bool request( const QString &realm, QString &username /In,Out/, QString &password /In,Out/, const QString &message = QString() );

    virtual bool requestMasterPassword( QString &password /In,Out/, bool stored = false );

};

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