KNewStuff

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

KDE's Doxygen guidelines are available online.