1/*
2 This file is part of KDE.
3
4 SPDX-FileCopyrightText: 2009 Eckhart Wörner <ewoerner@kde.org>
5 SPDX-FileCopyrightText: 2009 Frederik Gladhorn <gladhorn@kde.org>
6
7 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
8*/
9
10#ifndef ATTICA_PROVIDERMANAGER_H
11#define ATTICA_PROVIDERMANAGER_H
12
13#include <QNetworkReply>
14#include <QUrl>
15
16#include "attica_export.h"
17#include "provider.h"
18
19/*!
20 * \namespace Attica
21 * \inmodule Attica
22 * \brief The Attica namespace.
23 */
24namespace Attica
25{
26/*!
27 * \class Attica::ProviderManager
28 * \inmodule Attica
29 * \inheaderfile Attica/ProviderManager
30 *
31 * \brief Attica ProviderManager.
32 *
33 * This class is the primary access to Attica's functions.
34 * Use the ProviderManager to load Open Collaboration Service providers,
35 * either the default system ones, or from XML or custom locations.
36 *
37 * \section1 Provider Files
38 * Provider files are defined here:
39 * http://www.freedesktop.org/wiki/Specifications/open-collaboration-services
40 *
41 * \section1 Basic Use
42 *
43 * See addProviderFileToDefaultProviders(const QUrl &url) for an example of
44 * what the provider file sohuld look like. You can add providers to the
45 * ProviderManager as either raw XML data using addProviderFromXml(const QString &providerXml),
46 * or from a file somewhere on the system through addProviderFile(const QUrl &file),
47 * or you can simply load the default providers provided by your system
48 * (which generally means KDE's provider opendesktop.org).
49 *
50 * Importantly, to be able to detect when the ProviderManager is ready to
51 * manage things, before initialising it you will want to connect to the
52 * providerAdded(const Attica::Provider &provider) signal, which is fired
53 * every time a new provider is added to the manager.
54 *
55 * If you manually add all providers from XML, you can expect this to happen
56 * immediately. This means that once you have added your providers that way,
57 * you can access them through the providers() function, which returns
58 * a list of all loaded Providers.
59 *
60 * Once you have loaded a Provider, you can use its functions to access the
61 * services offered by that provider.
62 */
63class ATTICA_EXPORT ProviderManager : public QObject
64{
65 Q_OBJECT
66
67public:
68 /*!
69 * \value NoFlags
70 * \value DisablePlugins
71 */
72 enum ProviderFlag {
73 NoFlags = 0x0,
74 DisablePlugins = 0x1,
75 };
76 Q_DECLARE_FLAGS(ProviderFlags, ProviderFlag)
77
78 /*!
79 *
80 */
81 ProviderManager(const ProviderFlags &flags = NoFlags);
82 ~ProviderManager() override;
83
84 /*!
85 * Load available providers from configuration
86 */
87 void loadDefaultProviders();
88
89 /*!
90 * The list of provider files that get loaded by loadDefaultProviders.
91 * Each of these files can contain multiple providers.
92 */
93 QList<QUrl> defaultProviderFiles();
94
95 /*!
96 Add a provider file to the default providers (xml that contains provider descriptions).
97 Provider files contain information about each provider:
98 \badcode
99 <providers>
100 <provider>
101 <id>opendesktop</id>
102 <location>https://api.opendesktop.org/v1/</location>
103 <name>openDesktop.org</name>
104 <icon></icon>
105 <termsofuse>https://opendesktop.org/terms/</termsofuse>
106 <register>https://opendesktop.org/usermanager/new.php</register>
107 <services>
108 <person ocsversion="1.3" />
109 <friend ocsversion="1.3" />
110 <message ocsversion="1.3" />
111 <activity ocsversion="1.3" />
112 <content ocsversion="1.3" />
113 <fan ocsversion="1.3" />
114 <knowledgebase ocsversion="1.3" />
115 <event ocsversion="1.3" />
116 </services>
117 </provider>
118 </providers>
119 \endcode
120
121 \a url the url of the provider file
122 */
123 void addProviderFileToDefaultProviders(const QUrl &url);
124
125 /*!
126 *
127 */
128 void removeProviderFileFromDefaultProviders(const QUrl &url);
129
130 /*!
131 * Suppresses the authentication, so that the application can take care of authenticating itself
132 */
133 void setAuthenticationSuppressed(bool suppressed);
134
135 /*!
136 * Remove all providers and provider files that have been loaded
137 */
138 void clear();
139
140 /*!
141 * Parse a xml file containing a provider description
142 */
143 void addProviderFromXml(const QString &providerXml);
144
145 /*!
146 *
147 */
148 void addProviderFile(const QUrl &file);
149
150 /*!
151 *
152 */
153 QList<QUrl> providerFiles() const;
154
155 /*!
156 * Returns all loaded providers
157 */
158 QList<Provider> providers() const;
159
160 /*!
161 * Returns whether there's a provider with base url \a provider
162 */
163 bool contains(const QUrl &provider) const;
164
165 /*!
166 * Returns the provider with \a url base url.
167 */
168 Provider providerByUrl(const QUrl &url) const;
169
170 /*!
171 * Returns the provider for a given provider \a url.
172 */
173 Provider providerFor(const QUrl &url) const;
174
175Q_SIGNALS:
176 /*!
177 *
178 */
179 void providerAdded(const Attica::Provider &provider);
180
181 /*!
182 *
183 */
184 void defaultProvidersLoaded();
185
186 /*!
187 *
188 */
189 void authenticationCredentialsMissing(const Provider &provider);
190
191 /*!
192 *
193 */
194 void failedToLoad(const QUrl &provider, QNetworkReply::NetworkError error);
195
196private Q_SLOTS:
197 ATTICA_NO_EXPORT void fileFinished(const QString &url);
198 ATTICA_NO_EXPORT void authenticate(QNetworkReply *, QAuthenticator *);
199 ATTICA_NO_EXPORT void proxyAuthenticationRequired(const QNetworkProxy &proxy, QAuthenticator *authenticator);
200 ATTICA_NO_EXPORT void slotLoadDefaultProvidersInternal();
201
202private:
203 ProviderManager(const ProviderManager &other) = delete;
204 ProviderManager &operator=(const ProviderManager &other) = delete;
205
206 ATTICA_NO_EXPORT PlatformDependent *loadPlatformDependent(const ProviderFlags &flags);
207
208 ATTICA_NO_EXPORT void parseProviderFile(const QString &xmlString, const QUrl &url);
209
210 class Private;
211 Private *const d;
212};
213
214Q_DECLARE_OPERATORS_FOR_FLAGS(ProviderManager::ProviderFlags)
215
216}
217
218#endif
219

source code of attica/src/providermanager.h