Kgapi

accountmanager.h
1/*
2 SPDX-FileCopyrightText: 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 <QList>
10#include <QObject>
11
12#include "account.h"
13#include "kgapicore_export.h"
14
15class QUrl;
16
17namespace KGAPI2
18{
19
20class AccountManager;
21/**
22 * @brief AccountPromise is a result of asynchronous operations of AccountManager
23 *
24 * The AccountPromise is returned by AccountManager and will emit @p finished()
25 * signal when the asynchronous retrieval of the Account has finished.
26 *
27 * The object will delete itself once @p finished signal is emitted.
28 */
29class KGAPICORE_EXPORT AccountPromise : public QObject
30{
31 Q_OBJECT
32public:
33 ~AccountPromise() override;
34
35 AccountPtr account() const;
36
37 bool hasError() const;
38 QString errorText() const;
39
40Q_SIGNALS:
41 /**
42 * @brief The retrieval has finished and the Account can be retrieved.
43 *
44 * The object is automatically scheduled for deletion after this signal
45 * is emitted.
46 */
48
49private:
50 AccountPromise(QObject *parent = nullptr);
51 Q_DISABLE_COPY(AccountPromise)
52
53 friend class AccountManager;
54 class Private;
56};
57
58class KGAPICORE_EXPORT AccountManager : public QObject
59{
60 Q_OBJECT
61public:
62 ~AccountManager() override;
63
64 static AccountManager *instance();
65
66 /**
67 * @brief Asynchronously returns an authenticated account for given conditions
68 *
69 * The returned account is guaranteed to be authenticated against at least the
70 * requested @p scopes, but it may be authenticated against more scopes.
71 * If an account for the given @p apiKey and @p accountName already exists
72 * but is not authenticated against all the scopes the user will be presented
73 * with a prompt to confirm the missing scopes.
74 *
75 * If no such account exists, user will be prompted with full authentication
76 * process.
77 *
78 * The returned account is guaranteed to be authenticated, however the tokens
79 * may be expired. It's up to the caller to ensure the tokens are refreshed
80 * using @p refreshTokens method.
81 *
82 * @p apiSecret is only used to authenticate new account or missing scopes
83 * and is not stored anywhere.
84 *
85 * @see refreshTokens, hasAccount
86 */
87 AccountPromise *getAccount(const QString &apiKey, const QString &apiSecret, const QString &accountName, const QList<QUrl> &scopes);
88
89 /**
90 * @brief Asynchronously refreshes tokens in given Account
91 *
92 * The returned account is guaranteed to be authenticated against at least
93 * the requested @p scopes, but it may be authenticated against more scopes.
94 * If an account does not exist, it will be created (see AccountManager::getAccount()).
95 *
96 * @p apiSecret is only used to authenticate a new account.
97 *
98 * @see getAccount
99 */
100 AccountPromise *refreshTokens(const QString &apiKey, const QString &apiSecret, const QString &accountName);
101
102 /**
103 * @brief Asynchronously checks whether the specified account exists.
104 *
105 * Optionally, when non-empty list of @p scopes is provided this method also
106 * checks whether, if the account exists, it is authenticated against the
107 * provided scopes.
108 *
109 * The AccountPromise will have the discovered account set if it is found,
110 * otherwise it's set to null.
111 */
112 AccountPromise *findAccount(const QString &aipKey, const QString &accountName, const QList<QUrl> &scopes = {});
113
114 /**
115 * @brief Asynchronously remove given scopes from authenticated account.
116 *
117 * Removes the given scopes from the account authenticated scopes, so that
118 * next time the account is requested with any of the removed scopes the user
119 * will be presented with a prompt to confirm access again.
120 */
121 void removeScopes(const QString &apiKey, const QString &accountName, const QList<QUrl> &removeScopes);
122
123protected:
124 explicit AccountManager(QObject *parent = nullptr);
125 Q_DISABLE_COPY(AccountManager)
126
127 static AccountManager *sInstance;
128 class Private;
130};
131
132}
AccountPromise is a result of asynchronous operations of AccountManager.
void finished(KGAPI2::AccountPromise *self)
The retrieval has finished and the Account can be retrieved.
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 Nov 29 2024 11:54:35 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.