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

source code of attica/src/providermanager.h