Syndication

loader.h
1 /*
2  loader.h
3  SPDX-FileCopyrightText: 2001, 2002, 2003 Frerich Raabe <[email protected]>
4 
5  SPDX-License-Identifier: BSD-2-Clause
6 */
7 
8 #ifndef SYNDICATION_LOADER_H
9 #define SYNDICATION_LOADER_H
10 
11 #include <syndication/global.h>
12 
13 #include "syndication_export.h"
14 
15 #include <QObject>
16 
17 class QUrl;
18 
19 namespace Syndication
20 {
21 class DataRetriever;
22 class Feed;
23 //@cond PRIVATE
24 typedef QSharedPointer<Feed> FeedPtr;
25 //@endcond
26 
27 /**
28  * This class is the preferred way of loading feed sources. Usage is very
29  * straightforward:
30  *
31  * \code
32  * Loader *loader = Loader::create();
33  * connect(loader, SIGNAL(loadingComplete(Loader*, FeedPtr, ErrorCode)),
34  * this, SLOT(slotLoadingComplete(Loader*, FeedPtr, ErrorCode)));
35  * loader->loadFrom("http://www.blah.org/foobar.rdf");
36  * \endcode
37  *
38  * This creates a Loader object, connects it's loadingComplete() signal to
39  * your custom slot and then makes it load the file
40  * 'http://www.blah.org/foobar.rdf'. You could've
41  * done something like this as well:
42  *
43  * \code
44  * // create the Loader, connect it's signal...
45  * loader->loadFrom("/home/myself/some-script.py", new OutputRetriever);
46  * \endcode
47  *
48  * That'd make the Loader use a custom algorithm for retrieving the RSS data;
49  * 'OutputRetriever' will make it execute the script
50  * '/home/myself/some-script.py' and assume whatever that script prints to
51  * stdout is RSS/Azom markup. This is e.g. handy for conversion scripts, which
52  * download a HTML file and convert it's contents into RSS markup.
53  *
54  * No matter what kind of retrieval algorithm you employ, your
55  * 'slotLoadingComplete' method might look like this:
56  *
57  * \code
58  * void MyClass::slotLoadingComplete(Loader* loader, FeedPtr feed, ErrorCode status)
59  * {
60  * // Note that Loader::~Loader() is private, so you cannot delete Loader instances.
61  * // You don't need to do that anyway since Loader instances delete themselves.
62  *
63  * if (status != Syndication::Success)
64  * return;
65  *
66  * QString title = feed->title();
67  * // do whatever you want with the information.
68  * }
69  * \endcode
70  */
71 class SYNDICATION_EXPORT Loader : public QObject
72 {
73  Q_OBJECT
74 
75 public:
76  /**
77  * Constructs a Loader instance. This is pretty much what the
78  * default constructor would do, except that it ensures that all
79  * Loader instances have been allocated on the heap (this is
80  * required so that Loader's can delete themselves safely after they
81  * emitted the loadingComplete() signal.).
82  * @return A pointer to a new Loader instance.
83  */
84  static Loader *create();
85 
86  /**
87  * Convenience method. Does the same as the above method except that
88  * it also does the job of connecting the loadingComplete() signal
89  * to the given slot for you.
90  * @param object A QObject which features the specified slot
91  * @param slot Which slot to connect to.
92  */
93  static Loader *create(QObject *object, const char *slot);
94 
95  /**
96  * Loads the feed source referenced by the given URL using the
97  * specified retrieval algorithm. Make sure that you connected
98  * to the loadingComplete() signal before calling this method so
99  * that you're guaranteed to get notified when the loading finished.
100  * \note A Loader object cannot load from multiple URLs simultaneously;
101  * consequently, subsequent calls to loadFrom will be discarded
102  * silently, only the first loadFrom request will be executed.
103  * @param url A URL referencing the input file.
104  * @param retriever A subclass of DataRetriever which implements a
105  * specialized retrieval behaviour. Note that the ownership of the
106  * retriever is transferred to the Loader, i.e. the Loader will
107  * delete it when it doesn't need it anymore.
108  * @see DataRetriever, Loader::loadingComplete()
109  */
110  void loadFrom(const QUrl &url, DataRetriever *retriever);
111 
112  /**
113  * Retrieves the error code of the last loading process (if any).
114  */
115  Q_REQUIRED_RESULT ErrorCode errorCode() const;
116 
117  /**
118  * the error code returned from the retriever.
119  * Use this if you use your custom retriever implementation and
120  * need the specific error, not covered by errorCode().
121  */
122  Q_REQUIRED_RESULT int retrieverError() const;
123 
124  /**
125  * returns the URL of a feed discovered in the feed source
126  */
127  Q_REQUIRED_RESULT QUrl discoveredFeedURL() const;
128 
129  /**
130  * aborts the loading process
131  */
132  void abort();
133 
134 Q_SIGNALS:
135 
136  /**
137  * This signal gets emitted when the loading process triggered by
138  * calling loadFrom() finished.
139  * @param loader A pointer pointing to the loader object which
140  * emitted this signal; this is handy in case you connect multiple
141  * loaders to a single slot.
142  * @param feed In case errortus is Success, this parameter holds the
143  * parsed feed. If fetching/parsing failed, feed is NULL.
144  * @param error An error code telling whether there were any
145  * problems while retrieving or parsing the data.
146  * @see Feed, ErrorCode
147  */
148  void loadingComplete(Syndication::Loader *loader, Syndication::FeedPtr feed, Syndication::ErrorCode error);
149 
150 private Q_SLOTS:
151  SYNDICATION_NO_EXPORT void slotRetrieverDone(const QByteArray &data, bool success);
152 
153 private:
154  SYNDICATION_NO_EXPORT Loader();
155  Loader(const Loader &other);
156  Loader &operator=(const Loader &other);
157  SYNDICATION_NO_EXPORT ~Loader() override;
158  SYNDICATION_NO_EXPORT void discoverFeeds(const QByteArray &data);
159 
160  struct LoaderPrivate;
161  LoaderPrivate *const d;
162 };
163 
164 } // namespace Syndication
165 
166 #endif // SYNDICATION_LOADER_H
QAction * create(StandardGameAction id, const QObject *recvr, const char *slot, QObject *parent)
ErrorCode
error code indicating fetching or parsing errors
Definition: global.h:70
Q_SCRIPTABLE Q_NOREPLY void abort()
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon May 8 2023 03:57:11 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.