1/*
2 * Copyright (c) 2001, 2002, 2003 Frerich Raabe <raabe@kde.org>
3 *
4 * This program is distributed in the hope that it will be useful, but WITHOUT
5 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
6 * FOR A PARTICULAR PURPOSE. For licensing and distribution details, check the
7 * accompanying file 'COPYING'.
8 */
9
10#ifndef SYNDICATION_DATARETRIEVER_H
11#define SYNDICATION_DATARETRIEVER_H
12
13#include "ksyndication_export.h"
14
15#include <QtCore/QObject>
16#include <QtCore/QString>
17#include <QtCore/QProcess>
18
19namespace KIO
20{
21 class Job;
22}
23class KJob;
24class KUrl;
25
26class QByteArray;
27
28namespace Syndication
29{
30
31/**
32 * Abstract baseclass for all data retriever classes. Subclass this to add
33 * a new retrieval algorithm which can then be plugged into the RSS loader.
34 * @see Loader, FileRetriever, OutputRetriever
35 */
36class SYNDICATION_EXPORT DataRetriever : public QObject
37{
38 Q_OBJECT
39 public:
40 /**
41 * Default constructor.
42 */
43 DataRetriever();
44
45 /**
46 * Destructor.
47 */
48 virtual ~DataRetriever();
49
50 /**
51 * Retrieve data from the given URL. This method is supposed to get
52 * reimplemented by subclasses. It will be called by the Loader
53 * class in case it needs to retrieve the data.
54 *
55 * @param url the URL to retrieve data from
56 *
57 * @see Loader::loadFrom()
58 */
59 virtual void retrieveData(const KUrl& url) = 0;
60
61 /**
62 * @return An error code which might give a more precise information
63 * about what went wrong in case the 'success' flag returned with
64 * the dataRetrieved() signal was 'false'. Note that the meaning of
65 * the returned integer depends on the actual data retriever.
66 */
67 virtual int errorCode() const = 0;
68
69 /**
70 * aborts the retrieval process.
71 */
72 virtual void abort() = 0;
73
74 Q_SIGNALS:
75 /**
76 * Emit this signal to tell the Loader class that the retrieval
77 * process was finished.
78 * @param data Should contain the retrieved data and will get
79 * parsed by the Loader class.
80 * @param success Indicates whether there were any problems during
81 * the retrieval process. Pass 'true' to indicate that everything
82 * went seamlessy, 'false' to tell the Loader that something went
83 * wrong and that the data parameter might contain no or invalid
84 * data.
85 */
86
87 void dataRetrieved(const QByteArray& data, bool success);
88
89 private:
90 DataRetriever(const DataRetriever& other);
91 DataRetriever& operator=(const DataRetriever& other);
92};
93
94
95/**
96 * Implements a data retriever which executes a program and stores returned
97 * by the program on stdout. To be used with Loader::loadFrom().
98 * @see DataRetriever, Loader::loadFrom()
99 */
100class SYNDICATION_EXPORT OutputRetriever : public DataRetriever
101{
102 Q_OBJECT
103
104 public:
105
106 /**
107 * Default constructor.
108 */
109 OutputRetriever();
110
111 /**
112 * Destructor.
113 */
114 virtual ~OutputRetriever();
115
116 /**
117 * Executes the program referenced by the given URL and retrieves
118 * the data which the program prints to stdout.
119 * @param url An URL which is supposed to reference an executable
120 * file.
121 * @see Loader::loadFrom()
122 */
123 virtual void retrieveData(const KUrl& url);
124
125 /**
126 * @return The error code for the last process of retrieving data.
127 * 0 is returned in case there was no error, otherwise an error
128 * code which depends on the particular program which was run is
129 * returned.
130 */
131 virtual int errorCode() const;
132
133 virtual void abort() {}
134
135 private Q_SLOTS:
136 void slotFinished ( int exitCode, QProcess::ExitStatus exitStatus ) ;
137
138 private:
139 OutputRetriever(const OutputRetriever& other);
140 OutputRetriever& operator=(const OutputRetriever& other);
141
142 struct OutputRetrieverPrivate;
143 OutputRetrieverPrivate* const d;
144};
145
146/**
147 * Implements a file retriever, to be used with Loader::loadFrom().
148 * @see DataRetriever, Loader::loadFrom()
149 */
150class SYNDICATION_EXPORT FileRetriever : public DataRetriever
151{
152 Q_OBJECT
153
154 public:
155
156 /**
157 * Default constructor.
158 */
159 FileRetriever();
160
161 /**
162 * Destructor.
163 */
164 virtual ~FileRetriever();
165
166 /**
167 * Downloads the file referenced by the given URL and passes it's
168 * contents on to the Loader.
169 * @param url An URL referencing a file which is assumed to
170 * reference valid XML.
171 * @see Loader::loadFrom()
172 */
173 virtual void retrieveData(const KUrl& url);
174
175 /**
176 * @return The error code for the last process of retrieving data.
177 * The returned numbers correspond directly to the error codes
178 * <a href="http://developer.kde.org/documentation/library/cvs-api/classref/kio/KIO.html#Error">as
179 * defined by KIO</a>.
180 */
181 virtual int errorCode() const;
182
183 /**
184 * aborts the retrieval process.
185 */
186 virtual void abort();
187
188 /**
189 * sets whether the retriever should use the KHTML cache or
190 * always refetch the file. By default, the cache is used.
191 *
192 * @param enabled whether to use the HTML cache or not
193 */
194 static void setUseCache(bool enabled);
195
196 /**
197 * sets the user agent string sent to the remote server
198 *
199 * @param userAgent user agent string
200 */
201 static void setUserAgent(const QString& userAgent);
202
203 Q_SIGNALS:
204
205 /**
206 * Signals a permanent redirection. The redirection itself is
207 * handled internally, so you don't need to call Loader::loadFrom()
208 * with the new URL. This signal is useful in case you want to
209 * notify the user, or adjust a database entry.
210 *
211 * @param url the new URL after the redirection
212 *
213 * @see Loader::loadFrom()
214 */
215 void permanentRedirection(const KUrl& url);
216
217 protected Q_SLOTS:
218
219 void slotTimeout();
220
221 private Q_SLOTS:
222
223 void slotData(KIO::Job*job, const QByteArray& data);
224 void slotResult(KJob* job);
225 void slotPermanentRedirection(KIO::Job* job, const KUrl& fromUrl,
226 const KUrl& toUrl);
227
228 private:
229
230 static bool m_useCache;
231 static QString m_userAgent;
232
233 FileRetriever(const FileRetriever& other);
234 FileRetriever& operator=(const FileRetriever& other);
235
236 struct FileRetrieverPrivate;
237 FileRetrieverPrivate* const d;
238};
239
240} // namespace Syndication
241
242#endif // SYNDICATION_DATARETRIEVER_H
243