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 | |
23 | namespace KNSCore |
24 | { |
25 | |
26 | class ProviderBase; |
27 | |
28 | class ProviderBasePrivate |
29 | { |
30 | public: |
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 | */ |
44 | class 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) |
52 | public: |
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 (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 | |
194 | Q_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 (const QList<std::shared_ptr<KNSCore::Comment>> &); |
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 | |
235 | private: |
236 | friend class ProviderBubbleWrap; |
237 | std::unique_ptr<ProviderBasePrivate> d; |
238 | }; |
239 | |
240 | } |
241 | |