Attica

providermanager.h
1 /*
2  This file is part of KDE.
3 
4  SPDX-FileCopyrightText: 2009 Eckhart Wörner <[email protected]>
5  SPDX-FileCopyrightText: 2009 Frederik Gladhorn <[email protected]>
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  */
22 namespace 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  */
59 class ATTICA_EXPORT ProviderManager : public QObject
60 {
61  Q_OBJECT
62 
63 public:
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 #if ATTICA_ENABLE_DEPRECATED_SINCE(5, 23)
139  /**
140  * @deprecated Since 5.23, use contains(const QUrl&)
141  */
142  ATTICA_DEPRECATED_VERSION(5, 23, "Use ProviderManager::contains(const QUrl&)")
143  bool contains(const QString &provider) const;
144 #endif
145 
146  /**
147  * @returns whether there's a provider with base url @p provider
148  */
149  bool contains(const QUrl &provider) const;
150 
151  /**
152  * @returns the provider with @p url base url.
153  */
154  Provider providerByUrl(const QUrl &url) const;
155 
156  /**
157  * @returns the provider for a given provider @p url.
158  */
159  Provider providerFor(const QUrl &url) const;
160 
161 Q_SIGNALS:
162  void providerAdded(const Attica::Provider &provider);
163  void defaultProvidersLoaded();
164  void authenticationCredentialsMissing(const Provider &provider);
165  void failedToLoad(const QUrl &provider, QNetworkReply::NetworkError error);
166 
167 private Q_SLOTS:
168  ATTICA_NO_EXPORT void fileFinished(const QString &url);
169  ATTICA_NO_EXPORT void authenticate(QNetworkReply *, QAuthenticator *);
170  ATTICA_NO_EXPORT void proxyAuthenticationRequired(const QNetworkProxy &proxy, QAuthenticator *authenticator);
171  ATTICA_NO_EXPORT void slotLoadDefaultProvidersInternal();
172 
173 private:
174  ProviderManager(const ProviderManager &other) = delete;
175  ProviderManager &operator=(const ProviderManager &other) = delete;
176 
177  ATTICA_NO_EXPORT void initNetworkAccesssManager();
178  ATTICA_NO_EXPORT PlatformDependent *loadPlatformDependent(const ProviderFlags &flags);
179 
180  ATTICA_NO_EXPORT void parseProviderFile(const QString &xmlString, const QUrl &url);
181 
182  class Private;
183  Private *const d;
184 };
185 
186 Q_DECLARE_OPERATORS_FOR_FLAGS(ProviderManager::ProviderFlags)
187 
188 }
189 
190 #endif
The Attica namespace,.
QCA_EXPORT ProviderList providers()
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Dec 2 2023 04:07:50 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.