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