Warning, file /frameworks/attica/src/providermanager.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).

0001 /*
0002     This file is part of KDE.
0003 
0004     SPDX-FileCopyrightText: 2009 Eckhart W├Ârner <ewoerner@kde.org>
0005     SPDX-FileCopyrightText: 2009 Frederik Gladhorn <gladhorn@kde.org>
0006 
0007     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0008 */
0009 
0010 #ifndef ATTICA_PROVIDERMANAGER_H
0011 #define ATTICA_PROVIDERMANAGER_H
0012 
0013 #include <QNetworkReply>
0014 #include <QUrl>
0015 
0016 #include "attica_export.h"
0017 #include "provider.h"
0018 
0019 /**
0020  * The Attica namespace,
0021  */
0022 namespace Attica
0023 {
0024 /**
0025  * @class ProviderManager providermanager.h <Attica/ProviderManager>
0026  *
0027  * Attica ProviderManager
0028  *
0029  * This class is the primary access to Attica's functions.
0030  * Use the ProviderManager to load Open Collaboration Service providers,
0031  * either the default system ones, or from XML or custom locations.
0032  *
0033  * \section providerfiles Provider Files
0034  * Provider files are defined here:
0035  * http://www.freedesktop.org/wiki/Specifications/open-collaboration-services
0036  *
0037  * \section basicuse Basic Use
0038  *
0039  * See addProviderFileToDefaultProviders(const QUrl &url) for an example of
0040  * what the provider file sohuld look like. You can add providers to the
0041  * ProviderManager as either raw XML data using addProviderFromXml(const QString &providerXml),
0042  * or from a file somewhere on the system through addProviderFile(const QUrl &file),
0043  * or you can simply load the default providers provided by your system
0044  * (which generally means KDE's provider opendesktop.org).
0045  *
0046  * Importantly, to be able to detect when the ProviderManager is ready to
0047  * manage things, before initialising it you will want to connect to the
0048  * providerAdded(const Attica::Provider &provider) signal, which is fired
0049  * every time a new provider is added to the manager.
0050  *
0051  * If you manually add all providers from XML, you can expect this to happen
0052  * immediately. This means that once you have added your providers that way,
0053  * you can access them through the providers() function, which returns
0054  * a list of all loaded Providers.
0055  *
0056  * Once you have loaded a Provider, you can use its functions to access the
0057  * services offered by that provider.
0058  */
0059 class ATTICA_EXPORT ProviderManager : public QObject
0060 {
0061     Q_OBJECT
0062 
0063 public:
0064     enum ProviderFlag {
0065         NoFlags = 0x0,
0066         DisablePlugins = 0x1,
0067     };
0068     Q_DECLARE_FLAGS(ProviderFlags, ProviderFlag)
0069 
0070     ProviderManager(const ProviderFlags &flags = NoFlags);
0071     ~ProviderManager() override;
0072 
0073     /**
0074      * Load available providers from configuration
0075      */
0076     void loadDefaultProviders();
0077 
0078     /**
0079      * The list of provider files that get loaded by loadDefaultProviders.
0080      * Each of these files can contain multiple providers.
0081      * @return list of provider file urls
0082      */
0083     QList<QUrl> defaultProviderFiles();
0084 
0085     /**
0086     * Add a provider file to the default providers (xml that contains provider descriptions).
0087       Provider files contain information about each provider:
0088      <pre>
0089      <providers>
0090      <provider>
0091         <id>opendesktop</id>
0092         <location>https://api.opendesktop.org/v1/</location>
0093         <name>openDesktop.org</name>
0094         <icon></icon>
0095         <termsofuse>https://opendesktop.org/terms/</termsofuse>
0096         <register>https://opendesktop.org/usermanager/new.php</register>
0097         <services>
0098             <person ocsversion="1.3" />
0099             <friend ocsversion="1.3" />
0100             <message ocsversion="1.3" />
0101             <activity ocsversion="1.3" />
0102             <content ocsversion="1.3" />
0103             <fan ocsversion="1.3" />
0104             <knowledgebase ocsversion="1.3" />
0105             <event ocsversion="1.3" />
0106         </services>
0107      </provider>
0108      </providers>
0109      </pre>
0110     * @param url the url of the provider file
0111     */
0112     void addProviderFileToDefaultProviders(const QUrl &url);
0113 
0114     void removeProviderFileFromDefaultProviders(const QUrl &url);
0115 
0116     /**
0117      * Suppresses the authentication, so that the application can take care of authenticating itself
0118      */
0119     void setAuthenticationSuppressed(bool suppressed);
0120 
0121     /**
0122      * Remove all providers and provider files that have been loaded
0123      */
0124     void clear();
0125 
0126     /**
0127      * Parse a xml file containing a provider description
0128      */
0129     void addProviderFromXml(const QString &providerXml);
0130     void addProviderFile(const QUrl &file);
0131     QList<QUrl> providerFiles() const;
0132 
0133     /**
0134      * @returns all loaded providers
0135      */
0136     QList<Provider> providers() const;
0137 
0138 #if ATTICA_ENABLE_DEPRECATED_SINCE(5, 23)
0139     /**
0140      * @deprecated Since 5.23, use contains(const QUrl&)
0141      */
0142     ATTICA_DEPRECATED_VERSION(5, 23, "Use ProviderManager::contains(const QUrl&)")
0143     bool contains(const QString &provider) const;
0144 #endif
0145 
0146     /**
0147      * @returns whether there's a provider with base url @p provider
0148      */
0149     bool contains(const QUrl &provider) const;
0150 
0151     /**
0152      * @returns the provider with @p url base url.
0153      */
0154     Provider providerByUrl(const QUrl &url) const;
0155 
0156     /**
0157      * @returns the provider for a given provider @p url.
0158      */
0159     Provider providerFor(const QUrl &url) const;
0160 
0161 Q_SIGNALS:
0162     void providerAdded(const Attica::Provider &provider);
0163     void defaultProvidersLoaded();
0164     void authenticationCredentialsMissing(const Provider &provider);
0165     void failedToLoad(const QUrl &provider, QNetworkReply::NetworkError error);
0166 
0167 private Q_SLOTS:
0168     ATTICA_NO_EXPORT void fileFinished(const QString &url);
0169     ATTICA_NO_EXPORT void authenticate(QNetworkReply *, QAuthenticator *);
0170     ATTICA_NO_EXPORT void proxyAuthenticationRequired(const QNetworkProxy &proxy, QAuthenticator *authenticator);
0171     ATTICA_NO_EXPORT void slotLoadDefaultProvidersInternal();
0172 
0173 private:
0174     ProviderManager(const ProviderManager &other) = delete;
0175     ProviderManager &operator=(const ProviderManager &other) = delete;
0176 
0177     ATTICA_NO_EXPORT void initNetworkAccesssManager();
0178     ATTICA_NO_EXPORT PlatformDependent *loadPlatformDependent(const ProviderFlags &flags);
0179 
0180     ATTICA_NO_EXPORT void parseProviderFile(const QString &xmlString, const QUrl &url);
0181 
0182     class Private;
0183     Private *const d;
0184 };
0185 
0186 Q_DECLARE_OPERATORS_FOR_FLAGS(ProviderManager::ProviderFlags)
0187 
0188 }
0189 
0190 #endif