1 /*
2     SPDX-FileCopyrightText: 2012-2018 Daniel Vrátil <dvratil@kde.org>
3 
4     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5 */
6 
7 #pragma once
8 
9 #include <QString>
10 #include <QUrl>
11 #include <QMetaType>
12 #include <QSharedPointer>
13 
14 #include "kgapicore_export.h"
15 #include "types.h"
16 
17 namespace KGAPI2
18 {
19 
20 /**
21  * @headerfile account.h
22  * @brief A Google account
23  *
24  * This class represents a single Google account. The account is uniquely
25  * identified by Account::accountName (which is actually the user's GMail address).
26  *
27  * The class stores an access token, refresh token (to retrieve a new access token
28  * when the old one expires) and list of scopes (APIs that current access token
29  * can be used to access).
30  *
31  * Unlike in previous versions, account management is not handled by LibKGAPI
32  * anymore and it's up to programmer to store the account in a persistent storage.
33  *
34  * To obtain a new account, use AuthJob.
35  *
36  * @author Daniel Vrátil <dvratil@redhat.com>
37  * @since 0.1
38  */
39 class KGAPICORE_EXPORT Account
40 {
41 
42   public:
43     /**
44      * @brief Constructs an invalid account.
45      */
46     Account();
47 
48     /**
49      * @brief Constructs a new valid account
50      *
51      * @param account Google account name (usually user.name@gmail.com)
52      * @param accessToken Access token to \p scopes for \p account
53      * @param refreshToken Refresh token
54      * @param scopes List of scopes
55      */
56     explicit Account(const QString &account, const QString &accessToken = QString(),
57                      const QString &refreshToken = QString(),
58                      const QList< QUrl > &scopes = QList< QUrl >());
59 
60     /**
61      * @brief Copy constructor
62      */
63     Account(const Account &other);
64 
65     /**
66      * @brief Destructor
67      */
68     virtual ~Account();
69 
70 
71     bool operator==(const Account &other) const;
72 
73     /**
74      * @returns Returns unique account identifier
75      */
76     QString accountName() const;
77 
78     /**
79      * Sets account name.
80      *
81      * @param accountName
82      */
83     void setAccountName(const QString &accountName);
84 
85     /**
86      * @return Returns access token.
87      */
88     QString accessToken() const;
89 
90     /**
91      * Sets a new access token.
92      *
93      * @param accessToken
94      */
95     void setAccessToken(const QString &accessToken);
96 
97     /**
98      * @return Returns refresh token.
99      */
100     QString refreshToken() const;
101 
102     /**
103      * Sets a new refresh token for the access token.
104      *
105      * @param refreshToken
106      */
107     void setRefreshToken(const QString &refreshToken);
108 
109     /**
110      * @return Returns list of scopes the account is authenticated against.
111      */
112     QList< QUrl > scopes() const;
113 
114     /**
115      * \brief Sets new scopes.
116      *
117      * @note Note that changing scopes requires makes current tokens invalid.
118      * This means that when this Account is used next time, AuthJob will be
119      * automatically started and user will be prompted with a dialog to grant
120      * access to all scopes.
121      *
122      * @param scopes
123      */
124     void setScopes(const QList< QUrl > &scopes);
125 
126     /**
127      * Adds a single scope to account scopes.
128      *
129      * @param scope
130      * @see Account::setScopes(const QList<QUrl>)
131      */
132     void addScope(const QUrl &scope);
133 
134     /**
135      * Removes scope from the list.
136      *
137      * @param scope
138      * @see Account::setScopes(const QList<QUrl>)
139      */
140     void removeScope(const QUrl &scope);
141 
142     /**
143      * @since 2.0.82
144      * Returns expire date time token
145      */
146     QDateTime expireDateTime() const;
147 
148     /**
149      * @since 2.0.82
150      * set expire date time
151      */
152     void setExpireDateTime(const QDateTime &expire);
153 
154     /**
155      * Returns scope URL for AccountInfo service.
156      */
157     static QUrl accountInfoScopeUrl();
158 
159     /**
160      * Returns scope URL to retrieve AccountInfo with email.
161      */
162     static QUrl accountInfoEmailScopeUrl();
163 
164     /**
165      * Returns scope URL for Google Calendar service.
166      */
167     static QUrl calendarScopeUrl();
168 
169     /**
170      * Returns scope URL for Google Tasks service.
171      */
172     static QUrl tasksScopeUrl();
173 
174     /**
175      * Returns scope URL for Google Contacts service.
176      */
177     static QUrl contactsScopeUrl();
178 
179     /**
180      * Returns scope URL for Google Latitude service.
181      */
182     static QUrl latitudeScopeUrl();
183 
184     /**
185      * Returns scope URL for Google Blogger service.
186      */
187     static QUrl bloggerScopeUrl();
188 
189     /**
190      * Returns scope URL for Gmail service.
191      */
192     static QUrl mailScopeUrl();
193 
194     /**
195      * Returns scope URL for Drive service.
196      */
197     static QUrl driveScopeUrl();
198 private:
199     class Private;
200     Private * const d;
201 
202     /**
203      * @internal
204      * Whether scopes were changed or not.
205      *
206      * AuthJob reads this attribute when Account is passed to it to
207      * determine whether completely new process of authentication is needed,
208      * or whether just refreshing tokens is enough.
209      *
210      * When m_scopesChanged is \p true and AuthJob successffulyperforms full
211      * re-authentication it sets this attribute to \p false and next time it
212      * will just refresh existing tokens until the scopes are changed again.
213      */
214     bool m_scopesChanged; //krazy:exclude=dpointer
215 
216     friend class AuthJob;
217 
218 };
219 
220 } // namespace KGAPI2
221 
222 Q_DECLARE_METATYPE(KGAPI2::AccountPtr)
223 
224