QAbstractOAuth documentation

Change-Id: I29bb8b8002896ded989fe3c60e3e4311af8ef7d6
Reviewed-by: Topi Reiniö <topi.reinio@theqtcompany.com>
Reviewed-by: Timur Pocheptsov <timur.pocheptsov@theqtcompany.com>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

1 files changed, 197 insertions, 0 deletions

diff --git a/src/oauth/qabstractoauth.cpp b/src/oauth/qabstractoauth.cpp
index 6a49f77..dc72bd3 100644
--- a/src/oauth/qabstractoauth.cpp
+++ b/src/oauth/qabstractoauth.cpp
@@ -60,6 +60,116 @@ Q_DECLARE_METATYPE(QAbstractOAuth::Error)
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \class QAbstractOAuth
+    \inmodule QtNetworkAuth
+    \ingroup oauth
+    \brief The QAbstractOAuth class is the base of all
+    implementations of OAuth authentication methods.
+    \since 5.8
+
+    The class defines the basic interface of the OAuth
+    authentication classes. By inheriting this class, you
+    can create custom authentication methods for different web
+    services.
+
+    It also contains some functions to ease the process of
+    implementing different authentication flows.
+*/
+
+/*!
+    \enum QAbstractOAuth::Status
+
+    Indicates the current authentication status.
+
+    \value NotAuthenticated                 No token has been
+    retrieved.
+
+    \value TemporaryCredentialsReceived     Temporary credentials
+    have been received, this status is used in some OAuth
+    authetication methods.
+
+    \value Granted                          Token credentials have
+    been received and authenticated calls are allowed.
+
+    \value RefreshingToken                  New token credentials
+    have been requested.
+*/
+
+/*!
+    \enum QAbstractOAuth::Stage
+
+    Identifies an authentication stage.  It's passed to a
+    ModifyParametersFunction so that it can make different changes to
+    parameters at each call to it during the process of
+    authentication.
+
+    \value RequestingTemporaryCredentials   Preparing the temporary
+    credentials request.
+
+    \value RequestingAuthorization          Preparing the
+    authorization grant URL.
+
+    \value RequestingAccessToken            Preparing the token
+    request.
+*/
+
+/*!
+    \enum QAbstractOAuth::Error
+
+    Indicates the latest received error.
+
+    \value NoError                          No error has ocurred.
+
+    \value NetworkError                     Failed to connect to the server.
+
+    \value ServerError                      The server answered the
+    request with an error.
+
+    \value OAuthTokenNotFoundError          The server's response to
+    a token request provided no token identifier.
+
+    \value OAuthTokenSecretNotFoundError    The server's response to
+    a token request provided no token secret.
+
+    \value OAuthCallbackNotVerified         The authorization server
+    has not verified the supplied callback URI in the request. This
+    usually happens when the provided callback does not match with
+    the callback supplied during client registration.
+*/
+
+/*!
+    \property QAbstractOAuth::status
+    \brief This property holds the current authentication status.
+*/
+
+/*!
+    \property QAbstractOAuth::extraTokens
+    \brief This property holds the extra tokens received from the
+    server.
+*/
+
+/*!
+    \property QAbstractOAuth::authorizationUrl
+    \brief This property holds the URL used to request the Resource
+    Owner Authorization as described in:
+    \l{https://tools.ietf.org/html/rfc5849#section-2.2}{The OAuth
+    1.0 Protocol: Resource Owner Authorization}
+*/
+
+/*!
+    \fn void authorizeWithBrowser(const QUrl &url)
+    This signal is emitted when the URL generated by
+    \a resourceOwnerAuthorization is ready to be used in the web
+    browser to allow the application to impersonate the user.
+*/
+
+/*!
+    \fn void granted()
+    This signal is emitted when the authorization flow finishes
+    successfully.
+*/
+
 QAbstractOAuthPrivate::QAbstractOAuthPrivate(QNetworkAccessManager *manager) :
     QAbstractOAuthPrivate(QUrl(), manager)
 {}
@@ -119,15 +229,36 @@ QAbstractOAuth::QAbstractOAuth(QAbstractOAuthPrivate &dd, QObject *parent)
     qRegisterMetaType<QAbstractOAuth::Error>();
 }
 
+/*!
+    Destroys the abstract OAuth.
+*/
 QAbstractOAuth::~QAbstractOAuth()
 {}
 
+/*!
+    Returns the current network access manager used to send the
+    requests to the server during authentication flows or to make
+    authentication calls.
+
+    \sa setNetworkAccessManager(), QNetworkAccessManager
+*/
 QNetworkAccessManager *QAbstractOAuth::networkAccessManager() const
 {
     Q_D(const QAbstractOAuth);
     return d->networkAccessManagerPointer.data();
 }
 
+/*!
+    Sets the network manager to \a networkAccessManager.
+    QAbstractOAuth does not take ownership of
+    \a networkAccessManager. If no custom network access manager is
+    set, an internal network access manager is used.
+    This network access manager will be used
+    to make the request to the authentication server and the
+    authenticated request to the web service.
+
+    \sa networkAccessManager(), QNetworkAccessManager
+*/
 void QAbstractOAuth::setNetworkAccessManager(QNetworkAccessManager *networkAccessManager)
 {
     Q_D(QAbstractOAuth);
@@ -138,18 +269,32 @@ void QAbstractOAuth::setNetworkAccessManager(QNetworkAccessManager *networkAcces
     }
 }
 
+/*!
+    Returns the current authentication status.
+    \sa Status
+*/
 QAbstractOAuth::Status QAbstractOAuth::status() const
 {
     Q_D(const QAbstractOAuth);
     return d->status;
 }
 
+/*!
+    Returns the authorization request URL.
+    \sa setAuthorizationUrl()
+*/
 QUrl QAbstractOAuth::authorizationUrl() const
 {
     Q_D(const QAbstractOAuth);
     return d->authorizationUrl;
 }
 
+/*!
+    Sets the authorization request URL to \a url. This address
+    will be used to allow the user to grant the application the
+    ability to make authenticated calls on behalf of the user.
+    \sa authorizationUrl()
+*/
 void QAbstractOAuth::setAuthorizationUrl(const QUrl &url)
 {
     Q_D(QAbstractOAuth);
@@ -159,6 +304,11 @@ void QAbstractOAuth::setAuthorizationUrl(const QUrl &url)
     }
 }
 
+/*!
+    Sets the current status to \a status. This method is for use
+    by classes based on QAbstractOAuth.
+    \sa status()
+*/
 void QAbstractOAuth::setStatus(QAbstractOAuth::Status status)
 {
     Q_D(QAbstractOAuth);
@@ -168,24 +318,43 @@ void QAbstractOAuth::setStatus(QAbstractOAuth::Status status)
     }
 }
 
+/*!
+    Returns the reply handler currently in use.
+    \sa setReplyHandler(), QAbstractOAuthReplyHandler
+*/
 QAbstractOAuthReplyHandler *QAbstractOAuth::replyHandler() const
 {
     Q_D(const QAbstractOAuth);
     return d->replyHandler ? d->replyHandler.data() : d->defaultReplyHandler.data();
 }
 
+/*!
+    Sets the current reply handler to \a handler.
+    \note Does not take ownership of \a handler.
+*/
 void QAbstractOAuth::setReplyHandler(QAbstractOAuthReplyHandler *handler)
 {
     Q_D(QAbstractOAuth);
     d->replyHandler = handler;
 }
 
+/*!
+    Returns the current parameter-modification function.
+    \sa ModifyParametersFunction, setModifyParametersFunction(), Stage
+*/
 QAbstractOAuth::ModifyParametersFunction QAbstractOAuth::modifyParametersFunction() const
 {
     Q_D(const QAbstractOAuth);
     return d->modifyParametersFunction;
 }
 
+/*!
+    Sets the parameter-modification function. This function is used
+    to customize the parameters sent to the server during a specified
+    authorization stage. The number of calls to this function
+    depends on the flow used during the authentication.
+    \sa modifyParametersFunction(), ModifyParametersFunction, Stage
+*/
 void QAbstractOAuth::setModifyParametersFunction(
         const QAbstractOAuth::ModifyParametersFunction &modifyParametersFunction)
 {
@@ -193,12 +362,24 @@ void QAbstractOAuth::setModifyParametersFunction(
     d->modifyParametersFunction = modifyParametersFunction;
 }
 
+/*!
+    Returns the extra tokens received from the server during
+    authentication.
+    \sa extraTokensChanged()
+*/
 QVariantMap QAbstractOAuth::extraTokens() const
 {
     Q_D(const QAbstractOAuth);
     return d->extraTokens;
 }
 
+/*!
+    Returns the current callback string corresponding to the
+    current reply handler. The returned string is the string
+    sent to the server to specify the callback URI, or the word
+    identifying the alternative method in headless devices.
+    \sa replyHandler(), setReplyHandler()
+*/
 QString QAbstractOAuth::callback() const
 {
     Q_D(const QAbstractOAuth);
@@ -206,6 +387,14 @@ QString QAbstractOAuth::callback() const
                            : d->defaultReplyHandler->callback();
 }
 
+/*!
+    Builds the resource owner authorization URL to be used in the web
+    browser: \a url is used as the base URL and the query is created
+    using \a parameters. When the URL is ready, the
+    authorizeWithBrowser() signal will be emitted with the generated
+    URL.
+    \sa authorizeWithBrowser()
+*/
 void QAbstractOAuth::resourceOwnerAuthorization(const QUrl &url, const QVariantMap &parameters)
 {
     QUrl u = url;
@@ -213,6 +402,14 @@ void QAbstractOAuth::resourceOwnerAuthorization(const QUrl &url, const QVariantM
     Q_EMIT authorizeWithBrowser(u);
 }
 
+/*!
+    Generates a random string which could be used as state or nonce.
+    The parameter \a length determines the size of the generated
+    string.
+
+    \b {See also}: \l {https://tools.ietf.org/html/rfc5849#section-3.3}{The
+    OAuth 1.0 Protocol: Nonce and Timestamp}.
+*/
 QByteArray QAbstractOAuth::generateRandomString(quint8 length)
 {
     return QAbstractOAuthPrivate::generateRandomString(length);