Kgapi

account.h
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 <QMetaType>
10#include <QSharedPointer>
11#include <QString>
12#include <QUrl>
13
14#include "kgapicore_export.h"
15#include "types.h"
16
17namespace 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 */
39class KGAPICORE_EXPORT Account
40{
41public:
42 /**
43 * @brief Constructs an invalid account.
44 */
45 Account();
46
47 /**
48 * @brief Constructs a new valid account
49 *
50 * @param account Google account name (usually user.name@gmail.com)
51 * @param accessToken Access token to \p scopes for \p account
52 * @param refreshToken Refresh token
53 * @param scopes List of scopes
54 */
55 explicit Account(const QString &account,
56 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 bool operator==(const Account &other) const;
71
72 /**
73 * @returns Returns unique account identifier
74 */
75 [[nodiscard]] QString accountName() const;
76
77 /**
78 * Sets account name.
79 *
80 * @param accountName
81 */
82 void setAccountName(const QString &accountName);
83
84 /**
85 * @return Returns access token.
86 */
87 [[nodiscard]] QString accessToken() const;
88
89 /**
90 * Sets a new access token.
91 *
92 * @param accessToken
93 */
94 void setAccessToken(const QString &accessToken);
95
96 /**
97 * @return Returns refresh token.
98 */
99 [[nodiscard]] QString refreshToken() const;
100
101 /**
102 * Sets a new refresh token for the access token.
103 *
104 * @param refreshToken
105 */
106 void setRefreshToken(const QString &refreshToken);
107
108 /**
109 * @return Returns list of scopes the account is authenticated against.
110 */
111 [[nodiscard]] QList<QUrl> scopes() const;
112
113 /**
114 * \brief Sets new scopes.
115 *
116 * @note Note that changing scopes requires makes current tokens invalid.
117 * This means that when this Account is used next time, AuthJob will be
118 * automatically started and user will be prompted with a dialog to grant
119 * access to all scopes.
120 *
121 * @param scopes
122 */
123 void setScopes(const QList<QUrl> &scopes);
124
125 /**
126 * Adds a single scope to account scopes.
127 *
128 * @param scope
129 * @see Account::setScopes(const QList<QUrl>)
130 */
131 void addScope(const QUrl &scope);
132
133 /**
134 * Removes scope from the list.
135 *
136 * @param scope
137 * @see Account::setScopes(const QList<QUrl>)
138 */
139 void removeScope(const QUrl &scope);
140
141 /**
142 * @since 2.0.82
143 * Returns expire date time token
144 */
145 [[nodiscard]] QDateTime expireDateTime() const;
146
147 /**
148 * @since 2.0.82
149 * set expire date time
150 */
151 void setExpireDateTime(const QDateTime &expire);
152
153 /**
154 * Returns scope URL for AccountInfo service.
155 */
156 static QUrl accountInfoScopeUrl();
157
158 /**
159 * Returns scope URL to retrieve AccountInfo with email.
160 */
161 static QUrl accountInfoEmailScopeUrl();
162
163 /**
164 * Returns scope URL for accessing calendars in Google Calendar.
165 */
166 static QUrl calendarScopeUrl();
167
168
169 /**
170 * Returns scope URL for accessing Google Calendar events.
171 */
172 static QUrl calendarEventsScopeUrl();
173
174 /**
175 * Returns scope URL for Google Tasks service.
176 */
177 static QUrl tasksScopeUrl();
178
179 /**
180 * Returns scope URL for Google People service.
181 */
182 static QUrl peopleScopeUrl();
183
184 /**
185 * Returns scope URL for Google Latitude service.
186 */
187 static QUrl latitudeScopeUrl();
188
189 /**
190 * Returns scope URL for Google Blogger service.
191 */
192 static QUrl bloggerScopeUrl();
193
194 /**
195 * Returns scope URL for Gmail service.
196 */
197 static QUrl mailScopeUrl();
198
199 /**
200 * Returns scope URL for Drive service.
201 */
202 static QUrl driveScopeUrl();
203
204private:
205 class Private;
206 Private *const d;
207
208 /**
209 * @internal
210 * Whether scopes were changed or not.
211 *
212 * AuthJob reads this attribute when Account is passed to it to
213 * determine whether completely new process of authentication is needed,
214 * or whether just refreshing tokens is enough.
215 *
216 * When m_scopesChanged is \p true and AuthJob successffulyperforms full
217 * re-authentication it sets this attribute to \p false and next time it
218 * will just refresh existing tokens until the scopes are changed again.
219 */
220 bool m_scopesChanged; // krazy:exclude=dpointer
221
222 friend class AuthJob;
223};
224
225} // namespace KGAPI2
226
227Q_DECLARE_METATYPE(KGAPI2::AccountPtr)
A Google account.
Definition account.h:40
A job to authenticate against Google and fetch tokens.
Definition authjob.h:34
A job to fetch a single map tile described by a StaticMapUrl.
Definition blog.h:16
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:11:00 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.