1// SPDX-License-Identifier: LGPL-2.1-or-later
2// SPDX-FileCopyrightText: 2009 Jeremy Whiting <jpwhiting@kde.org>
3// SPDX-FileCopyrightText: 2009 Frederik Gladhorn <gladhorn@kde.org>
4// SPDX-FileCopyrightText: 2021 Dan Leinir Turthra Jensen <admin@leinir.dk>
5// SPDX-FileCopyrightText: 2024 Harald Sitter <sitter@kde.org>
6
7#pragma once
8
9#include <QDebug>
10#include <QList>
11#include <QString>
12#include <QUrl>
13
14#include <memory>
15
16#include "entry.h"
17#include "errorcode.h"
18
19#include "commentsmodel.h"
20#include "knewstuffcore_export.h"
21#include "searchrequest.h"
22
23namespace KNSCore
24{
25
26class ProviderBase;
27
28class ProviderBasePrivate
29{
30public:
31 ProviderBasePrivate(ProviderBase *qq)
32 : q(qq)
33 {
34 }
35 ProviderBase *q;
36 QStringList tagFilter;
37 QStringList downloadTagFilter;
38};
39
40/**
41 * @brief ProviderBase Interface
42 * Exported for our qtquick components. Do not install the header or use from the outside!
43 */
44class KNEWSTUFFCORE_EXPORT ProviderBase : public QObject
45{
46 Q_OBJECT
47 Q_PROPERTY(QString version READ version NOTIFY basicsLoaded)
48 Q_PROPERTY(QUrl website READ website NOTIFY basicsLoaded)
49 Q_PROPERTY(QUrl host READ host NOTIFY basicsLoaded)
50 Q_PROPERTY(QString contactEmail READ contactEmail NOTIFY basicsLoaded)
51 Q_PROPERTY(bool supportsSsl READ supportsSsl NOTIFY basicsLoaded)
52public:
53 ProviderBase(QObject *parent = nullptr);
54
55 /**
56 * A unique Id for this provider (the url in most cases)
57 */
58 [[nodiscard]] virtual QString id() const = 0;
59
60 /**
61 * Set the provider data xml, to initialize the provider.
62 * The Provider needs to have it's ID set in this function and cannot change it from there on.
63 */
64 virtual bool setProviderXML(const QDomElement &xmldata) = 0;
65
66 [[nodiscard]] virtual bool isInitialized() const = 0;
67
68 virtual void setCachedEntries(const KNSCore::Entry::List &cachedEntries) = 0;
69
70 /**
71 * Retrieves the common name of the provider.
72 *
73 * @return provider name
74 */
75 [[nodiscard]] virtual QString name() const = 0;
76
77 /**
78 * Retrieves the icon URL for this provider.
79 *
80 * @return icon URL
81 */
82 [[nodiscard]] virtual QUrl icon() const = 0; // FIXME use QIcon::fromTheme or pixmap?
83
84 /**
85 * load the given search and return given page
86 * @param sortMode string to select the order in which the results are presented
87 * @param searchstring string to search with
88 * @param page page number to load
89 *
90 * Note: the engine connects to loadingFinished() signal to get the result
91 */
92 virtual void loadEntries(const KNSCore::SearchRequest &request) = 0;
93 virtual void loadEntryDetails(const KNSCore::Entry &)
94 {
95 }
96 virtual void loadPayloadLink(const Entry &entry, int linkId) = 0;
97 /**
98 * Request a loading of comments from this provider. The engine listens to the
99 * commentsLoaded() signal for the result
100 *
101 * @note Implementation detail: All subclasses should connect to this signal
102 * and point it at a slot which does the actual work, if they support comments.
103 *
104 * @see commentsLoaded(const QList<shared_ptr<KNSCore::Comment>> comments)
105 * @since 5.63
106 */
107 virtual void loadComments(const KNSCore::Entry &, int /*commentsPerPage*/, int /*page*/)
108 {
109 }
110
111 /**
112 * Request loading of the details for a specific person with the given username.
113 * The engine listens to the personLoaded() for the result
114 *
115 * @note Implementation detail: All subclasses should connect to this signal
116 * and point it at a slot which does the actual work, if they support comments.
117 *
118 * @since 5.63
119 */
120 virtual void loadPerson(const QString & /*username*/)
121 {
122 }
123
124 /**
125 * @since 5.85
126 */
127 [[nodiscard]] virtual QString version() = 0;
128 /**
129 * @since 5.85
130 */
131 [[nodiscard]] virtual QUrl website() = 0;
132 /**
133 * @since 5.85
134 */
135 [[nodiscard]] virtual QUrl host() = 0;
136 /**
137 * The general contact email for this provider
138 * @return The general contact email for this provider
139 * @since 5.85
140 */
141 [[nodiscard]] virtual QString contactEmail() = 0;
142 /**
143 * Whether or not the provider supports SSL connections
144 * @return True if the server supports SSL connections, false if not
145 * @since 5.85
146 */
147 [[nodiscard]] virtual bool supportsSsl() = 0;
148
149 virtual bool userCanVote()
150 {
151 return false;
152 }
153 virtual void vote(const Entry & /*entry*/, uint /*rating*/)
154 {
155 }
156
157 virtual bool userCanBecomeFan()
158 {
159 return false;
160 }
161 virtual void becomeFan(const Entry & /*entry*/)
162 {
163 }
164
165 /**
166 * Set the tag filter used for entries by this provider
167 * @param tagFilter The new list of filters
168 * @see Engine::setTagFilter(QStringList)
169 * @since 5.51
170 */
171 void setTagFilter(const QStringList &tagFilter);
172 /**
173 * The tag filter used for downloads by this provider
174 * @return The list of filters
175 * @see Engine::setTagFilter(QStringList)
176 * @since 5.51
177 */
178 QStringList tagFilter() const;
179 /**
180 * Set the tag filter used for download items by this provider
181 * @param downloadTagFilter The new list of filters
182 * @see Engine::setDownloadTagFilter(QStringList)
183 * @since 5.51
184 */
185 void setDownloadTagFilter(const QStringList &downloadTagFilter);
186 /**
187 * The tag filter used for downloads by this provider
188 * @return The list of filters
189 * @see Engine::setDownloadTagFilter(QStringList)
190 * @since 5.51
191 */
192 QStringList downloadTagFilter() const;
193
194Q_SIGNALS:
195 void providerInitialized(KNSCore::ProviderBase *);
196
197 void entriesLoaded(const KNSCore::SearchRequest &, const KNSCore::Entry::List &);
198 void loadingDone(const KNSCore::SearchRequest &);
199 void loadingFailed(const KNSCore::SearchRequest &);
200
201 void entryDetailsLoaded(const KNSCore::Entry &);
202 void payloadLinkLoaded(const KNSCore::Entry &);
203 /**
204 * Fired when new comments have been loaded
205 * @param comments The list of newly loaded comments, in a depth-first order
206 * @since 5.63
207 */
208 void commentsLoaded(const QList<std::shared_ptr<KNSCore::Comment>> &comments);
209 /**
210 * Fired when the details of a person have been loaded
211 * @param author The person we've just loaded data for
212 * @since 5.63
213 */
214 void personLoaded(const std::shared_ptr<KNSCore::Author> &author);
215 /**
216 * Fired when the provider's basic information has been fetched and updated
217 * @since 5.85
218 */
219 void basicsLoaded();
220
221 /**
222 * Fires when the provider has loaded search presets. These represent interesting
223 * searches for the user, such as recommendations.
224 * @since 5.83
225 */
226 void searchPresetsLoaded(const QList<KNSCore::SearchPreset> &presets);
227
228 void signalInformation(const QString &);
229 void signalError(const QString &);
230 void signalErrorCode(KNSCore::ErrorCode::ErrorCode errorCode, const QString &message, const QVariant &metadata);
231 void categoriesMetadataLoaded(const QList<KNSCore::CategoryMetadata> &categories);
232 void tagFilterChanged();
233 void downloadTagFilterChanged();
234
235private:
236 friend class ProviderBubbleWrap;
237 std::unique_ptr<ProviderBasePrivate> d;
238};
239
240}
241

source code of knewstuff/src/core/providerbase_p.h