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 | |
19 | namespace KIO |
20 | { |
21 | class Job; |
22 | } |
23 | class KJob; |
24 | class KUrl; |
25 | |
26 | class QByteArray; |
27 | |
28 | namespace 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 | */ |
36 | class 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 | */ |
100 | class 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 | */ |
150 | class 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 | |