KNewStuff

provider.h
1/*
2 knewstuff3/provider.h
3 This file is part of KNewStuff2.
4 SPDX-FileCopyrightText: 2009 Jeremy Whiting <jpwhiting@kde.org>
5 SPDX-FileCopyrightText: 2009 Frederik Gladhorn <gladhorn@kde.org>
6 SPDX-FileCopyrightText: 2021 Dan Leinir Turthra Jensen <admin@leinir.dk>
7
8 SPDX-License-Identifier: LGPL-2.1-or-later
9*/
10
11#ifndef KNEWSTUFF3_PROVIDER_P_H
12#define KNEWSTUFF3_PROVIDER_P_H
13
14#include <QDebug>
15#include <QList>
16#include <QString>
17#include <QUrl>
18
19#include <memory>
20
21#include "entry.h"
22#include "errorcode.h"
23
24#include "knewstuffcore_export.h"
25
26namespace KNSCore
27{
28class ProviderPrivate;
29struct Comment;
30
31/**
32 * @short KNewStuff Base Provider class.
33 *
34 * This class provides accessors for the provider object.
35 * It should not be used directly by the application.
36 * This class is the base class and will be instantiated for
37 * static website providers.
38 *
39 * @author Jeremy Whiting <jpwhiting@kde.org>
40 * @deprecated since 6.9 Use ProviderBase to implement providers (only in-tree supported). Use ProviderCore to manage instances of base.
41 */
42class KNEWSTUFFCORE_EXPORT
43 KNEWSTUFFCORE_DEPRECATED_VERSION(6,
44 9,
45 "Use ProviderBase to implement providers (only in-tree supported). Use ProviderCore to manage instances of base.") Provider
46 : public QObject
47{
48 Q_OBJECT
49 Q_PROPERTY(QString version READ version WRITE setVersion NOTIFY basicsLoaded)
50 Q_PROPERTY(QUrl website READ website WRITE setWebsite NOTIFY basicsLoaded)
51 Q_PROPERTY(QUrl host READ host WRITE setHost NOTIFY basicsLoaded)
52 Q_PROPERTY(QString contactEmail READ contactEmail WRITE setContactEmail NOTIFY basicsLoaded)
53 Q_PROPERTY(bool supportsSsl READ supportsSsl WRITE setSupportsSsl NOTIFY basicsLoaded)
54public:
55 typedef QList<Provider *> List;
56
57 enum SortMode {
58 Newest,
59 Alphabetical,
60 Rating,
61 Downloads,
62 };
63 Q_ENUM(SortMode)
64
65 enum Filter {
66 None,
67 Installed,
68 Updates,
69 ExactEntryId,
70 };
71 Q_ENUM(Filter)
72
73 /**
74 * used to keep track of a search
75 * @deprecated since 6.9 Use KNSCore::SearchRequest
76 */
77 struct KNEWSTUFFCORE_DEPRECATED_VERSION(6, 9, "Use KNSCore::SearchRequest") SearchRequest {
78 SortMode sortMode;
79 Filter filter;
80 QString searchTerm;
81 QStringList categories;
82 int page;
83 int pageSize;
84
85 SearchRequest(SortMode sortMode_ = Downloads,
86 Filter filter_ = None,
87 const QString &searchTerm_ = QString(),
88 const QStringList &categories_ = QStringList(),
89 int page_ = -1,
90 int pageSize_ = 20)
91 : sortMode(sortMode_)
92 , filter(filter_)
93 , searchTerm(searchTerm_)
94 , categories(categories_)
95 , page(page_)
96 , pageSize(pageSize_)
97 {
98 }
99
100 QString hashForRequest() const;
101 bool operator==(const SearchRequest &other) const
102 {
103 return sortMode == other.sortMode && filter == other.filter && searchTerm == other.searchTerm && categories == other.categories
104 && page == other.page && pageSize == other.pageSize;
105 }
106 };
107
108 /**
109 * Describes a category: id/name/displayName
110 * @deprecated since 6.9 Use KNSCore::CategoryMetadata
111 */
112 struct KNEWSTUFFCORE_DEPRECATED_VERSION(6, 9, "Use KNSCore::CategoryMetadata") CategoryMetadata {
113 QString id;
114 QString name;
115 QString displayName;
116 };
117
118 /**
119 * @brief The SearchPresetTypes enum
120 * the preset type enum is a helper to identify the kind of label and icon
121 * the search preset should have if none are found.
122 * @since 5.83
123 * @deprecated since 6.9 Use KNSCore::SearchPreset::SearchPresetTypes
124 */
125 enum KNEWSTUFFCORE_DEPRECATED_VERSION(6, 9, "Use KNSCore::SearchPreset::SearchPresetTypes") SearchPresetTypes {
126 NoPresetType = 0,
127 GoBack, ///< preset representing the previous search.
128 Root, ///< preset indicating a root directory.
129 Start, ///< preset indicating the first entry.
130 Popular, ///< preset indicating popular items.
131 Featured, ///< preset for featured items.
132 Recommended, ///< preset for recommended. This may be customized by the server per user.
133 Shelf, ///< preset indicating previously acquired items.
134 Subscription, ///< preset indicating items that the user is subscribed to.
135 New, ///< preset indicating new items.
136 FolderUp, ///< preset indicating going up in the search result hierarchy.
137 AllEntries, ///< preset indicating all possible entries, such as a crawlable list. Might be intense to load.
138 };
139 /**
140 * Describes a search request that may come from the provider.
141 * This is used by the OPDS provider to handle the different urls.
142 * @since 5.83
143 * @deprecated since 6.9 Use KNSCore::SearchPreset
144 */
145 struct KNEWSTUFFCORE_DEPRECATED_VERSION(6, 9, "Use KNSCore::SearchPreset") SearchPreset {
146 SearchRequest request;
147 QString displayName;
148 QString iconName;
150 QString providerId; // not all providers can handle all search requests.
151 };
152
153 /**
154 * Constructor.
155 */
156 Provider();
157
158 /**
159 * Destructor.
160 */
161 ~Provider() override;
162
163 /**
164 * A unique Id for this provider (the url in most cases)
165 */
166 virtual QString id() const = 0;
167
168 /**
169 * Set the provider data xml, to initialize the provider.
170 * The Provider needs to have it's ID set in this function and cannot change it from there on.
171 */
172 virtual bool setProviderXML(const QDomElement &xmldata) = 0;
173
174 virtual bool isInitialized() const = 0;
175
176 virtual void setCachedEntries(const KNSCore::Entry::List &cachedEntries) = 0;
177
178 /**
179 * Retrieves the common name of the provider.
180 *
181 * @return provider name
182 */
183 virtual QString name() const;
184
185 /**
186 * Retrieves the icon URL for this provider.
187 *
188 * @return icon URL
189 */
190 virtual QUrl icon() const; // FIXME use QIcon::fromTheme or pixmap?
191
192 /**
193 * load the given search and return given page
194 * @param sortMode string to select the order in which the results are presented
195 * @param searchstring string to search with
196 * @param page page number to load
197 *
198 * Note: the engine connects to loadingFinished() signal to get the result
199 */
200 virtual void loadEntries(const KNSCore::Provider::SearchRequest &request) = 0;
201 virtual void loadEntryDetails(const KNSCore::Entry &)
202 {
203 }
204 virtual void loadPayloadLink(const Entry &entry, int linkId) = 0;
205 /**
206 * Request a loading of comments from this provider. The engine listens to the
207 * commentsLoaded() signal for the result
208 *
209 * @note Implementation detail: All subclasses should connect to this signal
210 * and point it at a slot which does the actual work, if they support comments.
211 *
212 * @see commentsLoaded(const QList<shared_ptr<KNSCore::Comment>> comments)
213 * @since 5.63
214 */
215 virtual void loadComments(const KNSCore::Entry &, int /*commentsPerPage*/, int /*page*/)
216 {
217 }
218
219 /**
220 * Request loading of the details for a specific person with the given username.
221 * The engine listens to the personLoaded() for the result
222 *
223 * @note Implementation detail: All subclasses should connect to this signal
224 * and point it at a slot which does the actual work, if they support comments.
225 *
226 * @since 5.63
227 */
228 virtual void loadPerson(const QString & /*username*/)
229 {
230 }
231
232 /**
233 * Request loading of the basic information for this provider. The engine listens
234 * to the basicsLoaded() signal for the result, which is also the signal the respective
235 * properties listen to.
236 *
237 * This is fired automatically on the first attempt to read one of the properties
238 * which contain this basic information, and you will not need to call it as a user
239 * of the class (just listen to the properties, which will update when the information
240 * has been fetched).
241 *
242 * @note Implementation detail: All subclasses should connect to this signal
243 * and point it at a slot which does the actual work, if they support fetching
244 * this basic information (if the information is set during construction, you will
245 * not need to worry about this).
246 *
247 * @see version()
248 * @see website()
249 * @see host();
250 * @see contactEmail()
251 * @see supportsSsl()
252 * @since 5.85
253 */
254 virtual void loadBasics()
255 {
256 }
257
258 /**
259 * @since 5.85
260 */
261 QString version() const;
262 /**
263 * @since 5.85
264 */
265 void setVersion(const QString &version);
266 /**
267 * @since 5.85
268 */
269 QUrl website() const;
270 /**
271 * @since 5.85
272 */
273 void setWebsite(const QUrl &website);
274 /**
275 * @since 5.85
276 */
277 QUrl host() const;
278 /**
279 * @param host The host used for this provider
280 * @since 5.85
281 */
282 void setHost(const QUrl &host);
283 /**
284 * The general contact email for this provider
285 * @return The general contact email for this provider
286 * @since 5.85
287 */
288 QString contactEmail() const;
289 /**
290 * Sets the general contact email address for this provider
291 * @param contactEmail The general contact email for this provider
292 * @since 5.85
293 */
294 void setContactEmail(const QString &contactEmail);
295 /**
296 * Whether or not the provider supports SSL connections
297 * @return True if the server supports SSL connections, false if not
298 * @since 5.85
299 */
300 bool supportsSsl() const;
301 /**
302 * Set whether or not the provider supports SSL connections
303 * @param supportsSsl True if the server supports SSL connections, false if not
304 * @since 5.85
305 */
306 void setSupportsSsl(bool supportsSsl);
307
308 virtual bool userCanVote()
309 {
310 return false;
311 }
312 virtual void vote(const Entry & /*entry*/, uint /*rating*/)
313 {
314 }
315
316 virtual bool userCanBecomeFan()
317 {
318 return false;
319 }
320 virtual void becomeFan(const Entry & /*entry*/)
321 {
322 }
323
324 /**
325 * Set the tag filter used for entries by this provider
326 * @param tagFilter The new list of filters
327 * @see Engine::setTagFilter(QStringList)
328 * @since 5.51
329 */
330 void setTagFilter(const QStringList &tagFilter);
331 /**
332 * The tag filter used for downloads by this provider
333 * @return The list of filters
334 * @see Engine::setTagFilter(QStringList)
335 * @since 5.51
336 */
337 QStringList tagFilter() const;
338 /**
339 * Set the tag filter used for download items by this provider
340 * @param downloadTagFilter The new list of filters
341 * @see Engine::setDownloadTagFilter(QStringList)
342 * @since 5.51
343 */
344 void setDownloadTagFilter(const QStringList &downloadTagFilter);
345 /**
346 * The tag filter used for downloads by this provider
347 * @return The list of filters
348 * @see Engine::setDownloadTagFilter(QStringList)
349 * @since 5.51
350 */
351 QStringList downloadTagFilter() const;
352
353Q_SIGNALS:
354 void providerInitialized(KNSCore::Provider *);
355
356 void loadingFinished(const KNSCore::Provider::SearchRequest &, const KNSCore::Entry::List &);
357 void loadingFailed(const KNSCore::Provider::SearchRequest &);
358
359 void entryDetailsLoaded(const KNSCore::Entry &);
360 void payloadLinkLoaded(const KNSCore::Entry &);
361 /**
362 * Fired when new comments have been loaded
363 * @param comments The list of newly loaded comments, in a depth-first order
364 * @since 5.63
365 */
366 void commentsLoaded(const QList<std::shared_ptr<KNSCore::Comment>> comments);
367 /**
368 * Fired when the details of a person have been loaded
369 * @param author The person we've just loaded data for
370 * @since 5.63
371 */
372 void personLoaded(const std::shared_ptr<KNSCore::Author> author);
373 /**
374 * Fired when the provider's basic information has been fetched and updated
375 * @since 5.85
376 */
378
379 /**
380 * Fires when the provider has loaded search presets. These represent interesting
381 * searches for the user, such as recommendations.
382 * @since 5.83
383 */
385
386 void signalInformation(const QString &);
387 void signalError(const QString &);
388 void signalErrorCode(KNSCore::ErrorCode::ErrorCode errorCode, const QString &message, const QVariant &metadata);
389
390 void categoriesMetadataLoded(const QList<KNSCore::Provider::CategoryMetadata> &categories);
391 void tagFilterChanged();
392 void downloadTagFilterChanged();
393
394protected:
395 void setName(const QString &name);
396 void setIcon(const QUrl &icon);
397
398private:
399 friend class ProviderBubbleWrap;
400 const std::unique_ptr<ProviderPrivate> d;
401 Q_DISABLE_COPY(Provider)
402};
403
404KNEWSTUFFCORE_EXPORT QDebug operator<<(QDebug, const Provider::SearchRequest &);
405}
406
407#endif
KNewStuff data entry container.
Definition entry.h:48
KNewStuff Base Provider class.
Definition provider.h:47
virtual void loadEntries(const KNSCore::Provider::SearchRequest &request)=0
load the given search and return given page
virtual void loadBasics()
Request loading of the basic information for this provider.
Definition provider.h:254
~Provider() override
Destructor.
virtual bool setProviderXML(const QDomElement &xmldata)=0
Set the provider data xml, to initialize the provider.
virtual void loadComments(const KNSCore::Entry &, int, int)
Request a loading of comments from this provider.
Definition provider.h:215
void personLoaded(const std::shared_ptr< KNSCore::Author > author)
Fired when the details of a person have been loaded.
void commentsLoaded(const QList< std::shared_ptr< KNSCore::Comment > > comments)
Fired when new comments have been loaded.
virtual QString id() const =0
A unique Id for this provider (the url in most cases)
SearchPresetTypes
The SearchPresetTypes enum the preset type enum is a helper to identify the kind of label and icon th...
Definition provider.h:125
@ Root
preset indicating a root directory.
Definition provider.h:128
@ Start
preset indicating the first entry.
Definition provider.h:129
@ New
preset indicating new items.
Definition provider.h:135
@ Subscription
preset indicating items that the user is subscribed to.
Definition provider.h:134
@ Shelf
preset indicating previously acquired items.
Definition provider.h:133
@ FolderUp
preset indicating going up in the search result hierarchy.
Definition provider.h:136
@ AllEntries
preset indicating all possible entries, such as a crawlable list. Might be intense to load.
Definition provider.h:137
@ GoBack
preset representing the previous search.
Definition provider.h:127
@ Popular
preset indicating popular items.
Definition provider.h:130
@ Recommended
preset for recommended. This may be customized by the server per user.
Definition provider.h:132
@ Featured
preset for featured items.
Definition provider.h:131
void basicsLoaded()
Fired when the provider's basic information has been fetched and updated.
virtual void loadPerson(const QString &)
Request loading of the details for a specific person with the given username.
Definition provider.h:228
void searchPresetsLoaded(const QList< KNSCore::Provider::SearchPreset > &presets)
Fires when the provider has loaded search presets.
Describes a category: id/name/displayName.
Definition provider.h:112
Describes a search request that may come from the provider.
Definition provider.h:145
used to keep track of a search
Definition provider.h:77
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:13:34 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.