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

KDE's Doxygen guidelines are available online.