Syndication

loader.h
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
19class QUrl;
20
21namespace Syndication
22{
23class DataRetriever;
24class Feed;
25//@cond PRIVATE
26typedef 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 */
73class SYNDICATION_EXPORT Loader : public QObject
74{
75 Q_OBJECT
76
77public:
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
136Q_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
152private Q_SLOTS:
153 SYNDICATION_NO_EXPORT void slotRetrieverDone(const QByteArray &data, bool success);
154
155private:
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
Q_SCRIPTABLE Q_NOREPLY void abort()
QAction * create(StandardAction id, const QObject *recvr, const char *slot, QObject *parent)
ErrorCode
error code indicating fetching or parsing errors
Definition global.h:70
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 17 2024 11:56:56 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.