1 | /* |
2 | This file is part of the kblog library. |
3 | |
4 | Copyright (c) 2004 Reinhold Kainhofer <reinhold@kainhofer.com> |
5 | Copyright (c) 2006-2007 Christian Weilbach <christian_weilbach@web.de> |
6 | Copyright (c) 2007 Mike McQuaid <mike@mikemcquaid.com> |
7 | |
8 | This library is free software; you can redistribute it and/or |
9 | modify it under the terms of the GNU Library General Public |
10 | License as published by the Free Software Foundation; either |
11 | version 2 of the License, or (at your option) any later version. |
12 | |
13 | This library is distributed in the hope that it will be useful, |
14 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
15 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
16 | Library General Public License for more details. |
17 | |
18 | You should have received a copy of the GNU Library General Public License |
19 | along with this library; see the file COPYING.LIB. If not, write to |
20 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
21 | Boston, MA 02110-1301, USA. |
22 | */ |
23 | |
24 | #ifndef KBLOG_BLOG_H |
25 | #define KBLOG_BLOG_H |
26 | |
27 | #include <kblog/kblog_export.h> |
28 | |
29 | #include <QtCore/QObject> |
30 | |
31 | template <class T,class S> class QMap; |
32 | |
33 | class KTimeZone; |
34 | class KUrl; |
35 | |
36 | /** |
37 | This is the main interface for blogging APIs. |
38 | It's methods represent the core functionality of a blogging API. |
39 | @author Reinhold Kainhofer, Christian Weilbach and Mike McQuaid. |
40 | */ |
41 | |
42 | /** |
43 | @file |
44 | This file is part of the library for accessing blogs and defines the |
45 | Blog class. |
46 | |
47 | @author Christian Weilbach \<christian_weilbach\@web.de\> |
48 | @author Mike McQuaid \<mike\@mikemcquaid.com\> |
49 | @author Reinhold Kainhofer \<reinhold\@kainhofer.com\> |
50 | */ |
51 | |
52 | /** Namespace for blog related classes. */ |
53 | namespace KBlog { |
54 | |
55 | class BlogPost; |
56 | class ; |
57 | class BlogMedia; |
58 | class BlogPrivate; |
59 | |
60 | /** |
61 | @brief |
62 | A class that provides methods to call functions on a supported blog |
63 | web application. |
64 | This is the main interface to the blogging client library. |
65 | |
66 | @author Christian Weilbach \<christian_weilbach\@web.de\> |
67 | @author Mike McQuaid \<mike\@mikemcquaid.com\> |
68 | @author Reinhold Kainhofer \<reinhold\@kainhofer.com\> |
69 | */ |
70 | |
71 | class KBLOG_EXPORT Blog : public QObject |
72 | { |
73 | Q_OBJECT |
74 | public: |
75 | /** |
76 | Constructor used by the remote interface implementations. |
77 | |
78 | @param server URL for the blog's remote interface. |
79 | @param parent the parent of this object, defaults to null. |
80 | @param applicationName the client application's name to use in the |
81 | HTTP user agent string, defaults to KBlog's own. |
82 | @param applicationVersion the client application's version to use in the |
83 | HTTP user agent string, defaults to KBlog's own. |
84 | */ |
85 | explicit Blog( const KUrl &server, QObject *parent = 0, |
86 | const QString &applicationName = QString(), |
87 | const QString &applicationVersion = QString() ); |
88 | |
89 | /** |
90 | Destroys the Blog object. |
91 | */ |
92 | virtual ~Blog(); |
93 | |
94 | /** |
95 | Enumeration for possible errors. |
96 | */ |
97 | enum ErrorType { |
98 | /** An error in the XML-RPC client. */ |
99 | XmlRpc, |
100 | /** An error in the syndication client. */ |
101 | Atom, |
102 | /** A parsing error. */ |
103 | ParsingError, |
104 | /** An error on authentication. */ |
105 | AuthenticationError, |
106 | /** An error where the method called is not supported by this object. */ |
107 | NotSupported, |
108 | /** Any other miscellaneous error. */ |
109 | Other |
110 | }; |
111 | |
112 | /** |
113 | Returns the HTTP user agent string used to make the HTTP requests. |
114 | */ |
115 | QString userAgent() const; |
116 | |
117 | /** |
118 | Sets the HTTP user agent string used to make the HTTP requests. |
119 | |
120 | @param applicationName the client application's name to use in the |
121 | HTTP user agent string. |
122 | @param applicationVersion the client application's version to use in the |
123 | HTTP user agent string. |
124 | @see userAgent() |
125 | */ |
126 | void setUserAgent( const QString &applicationName, |
127 | const QString &applicationVersion ); |
128 | |
129 | /** |
130 | Returns the name of the blogging API this object implements. |
131 | */ |
132 | virtual QString interfaceName() const = 0; |
133 | |
134 | /** |
135 | Sets the unique ID for the specific blog on the server. |
136 | @param blogId the ID of the blog to send/receive from. |
137 | @see blogId(); |
138 | */ |
139 | virtual void setBlogId( const QString &blogId ); |
140 | |
141 | /** |
142 | Returns the unique ID for the specific blog on the server. |
143 | @see setBlogId( const QString &blogId ); |
144 | */ |
145 | QString blogId() const; |
146 | |
147 | /** |
148 | Sets the password used in blog authentication. |
149 | @param password the blog's password. |
150 | |
151 | @see password(); |
152 | */ |
153 | virtual void setPassword( const QString &password ); |
154 | |
155 | /** |
156 | Returns the password of the blog. |
157 | @see setPassword( const QString & ); |
158 | */ |
159 | QString password() const; |
160 | |
161 | /** |
162 | Sets the username used in blog authentication. |
163 | @param username the blog's username. |
164 | @see username() |
165 | */ |
166 | virtual void setUsername( const QString &username ); |
167 | |
168 | /** |
169 | Returns the username used in blog authentication. |
170 | |
171 | @see setUsername( const QString & ) |
172 | */ |
173 | QString username() const; |
174 | |
175 | /** |
176 | Sets the URL for the blog's XML-RPC interface. |
177 | |
178 | @param url the blog's XML-RPC URL. |
179 | @see url() |
180 | */ |
181 | virtual void setUrl( const KUrl &url ); |
182 | |
183 | /** |
184 | Get the URL for the blog's XML-RPC interface. |
185 | |
186 | @see setUrl( const KUrl & ) |
187 | */ |
188 | KUrl url() const; |
189 | |
190 | /** |
191 | Sets the time zone of the blog's server. |
192 | |
193 | @param timeZone the time zone of the server. |
194 | @see timeZone() |
195 | */ |
196 | virtual void setTimeZone( const KTimeZone &timeZone ); |
197 | |
198 | /** |
199 | Get the time zone of the blog's server. |
200 | |
201 | @see void setTimeZone() |
202 | */ |
203 | KTimeZone timeZone(); |
204 | |
205 | /** |
206 | List a number of recent posts from the server. |
207 | The posts are returned in descending chronological order. |
208 | |
209 | @param number the number of posts to fetch. |
210 | @see listedRecentPosts( const QList<KBlog::BlogPost>& posts ) |
211 | */ |
212 | virtual void listRecentPosts( int number ) = 0; |
213 | |
214 | /** |
215 | Fetch a blog post from the server with a specific ID. |
216 | The ID of the existing post must be retrieved using getRecentPosts |
217 | and then be modified and provided to this method or a new BlogPost |
218 | created with the existing ID. |
219 | |
220 | @param post a blog post with the ID identifying the blog post to fetch. |
221 | @see fetchedPost() |
222 | @see listedRecentPosts( int number ) |
223 | */ |
224 | virtual void fetchPost( KBlog::BlogPost *post ) = 0; |
225 | |
226 | /** |
227 | Modify an existing blog post on the server. |
228 | The ID of the existing post must be retrieved using getRecentPosts |
229 | and then be modified and provided to this method or a new BlogPost |
230 | created with the existing ID. |
231 | |
232 | @param post the new blog post. |
233 | @see modifiedPost() |
234 | @see listedRecentPosts( int number ) |
235 | */ |
236 | virtual void modifyPost( KBlog::BlogPost *post ) = 0; |
237 | |
238 | /** |
239 | Create a new blog post on the server. |
240 | |
241 | @param post the blog post to create. |
242 | @see createdPost() |
243 | */ |
244 | virtual void createPost( KBlog::BlogPost *post ) = 0; |
245 | |
246 | /** |
247 | Remove an existing blog post from the server. |
248 | The BlogPost object representing the existing post must be retrieved |
249 | using getRecentPosts and then provided to this method. |
250 | |
251 | @param post* the blog post to remove. |
252 | @see removedPost() |
253 | @see listedRecentPosts( int number ) |
254 | */ |
255 | virtual void removePost( KBlog::BlogPost *post ) = 0; |
256 | |
257 | Q_SIGNALS: |
258 | /** |
259 | This signal is emitted when a listRecentPosts() job fetches a post |
260 | from the blogging server. |
261 | |
262 | @param posts the list of posts. |
263 | @see listRecentPosts() |
264 | */ |
265 | void listedRecentPosts( |
266 | const QList<KBlog::BlogPost>& posts ); |
267 | |
268 | /** |
269 | This signal is emitted when a createPost() job creates a new blog post |
270 | on the blogging server. |
271 | |
272 | @param post the created post. |
273 | @see createPost() |
274 | */ |
275 | void createdPost( KBlog::BlogPost *post ); |
276 | |
277 | /** |
278 | This signal is emitted when a fetchPost() job fetches a post |
279 | from the blogging server. |
280 | |
281 | @param post the fetched post. |
282 | @see fetchPost() |
283 | */ |
284 | void fetchedPost( KBlog::BlogPost *post ); |
285 | |
286 | /** |
287 | This signal is emitted when a modifyPost() job modifies a post |
288 | on the blogging server. |
289 | |
290 | @param post the modified post. |
291 | @see modifyPost() |
292 | */ |
293 | void modifiedPost( KBlog::BlogPost *post ); |
294 | |
295 | /** |
296 | This signal is emitted when a removePost() job removes a post |
297 | from the blogging server. |
298 | |
299 | @param post the removed post. |
300 | @see removePost() |
301 | */ |
302 | void removedPost( KBlog::BlogPost *post ); |
303 | |
304 | /** |
305 | This signal is emitted when an error occurs with XML parsing or a |
306 | structural problem. |
307 | |
308 | @param type the type of the error. |
309 | @param errorMessage the error message. |
310 | @see ErrorType |
311 | */ |
312 | void error( KBlog::Blog::ErrorType type, const QString &errorMessage ); |
313 | |
314 | /** |
315 | This signal is emitted when an error occurs with XML parsing or a |
316 | structural problem in an operation involving a blog post. |
317 | |
318 | @param type the type of the error. |
319 | @param errorMessage the error message. |
320 | @param post the post that caused the error. |
321 | @see ErrorType |
322 | */ |
323 | void errorPost( KBlog::Blog::ErrorType type, |
324 | const QString &errorMessage, KBlog::BlogPost *post ); |
325 | |
326 | /** |
327 | This signal is emitted when an error occurs with XML parsing or a |
328 | structural problem in an operation involving some blog media. |
329 | |
330 | @param type the type of the error. |
331 | @param errorMessage the error message. |
332 | @param media the media that caused the error. |
333 | @see ErrorType |
334 | */ |
335 | void errorMedia( KBlog::Blog::ErrorType type, |
336 | const QString &errorMessage, KBlog::BlogMedia *media ); |
337 | |
338 | /** |
339 | This signal is emitted when an error occurs with XML parsing or a |
340 | structural problem in an operation involving a blog post's comment. |
341 | |
342 | @param type the type of the error. |
343 | @param errorMessage the error message. |
344 | @param post the post that caused the error. |
345 | @param comment the comment that caused the error. |
346 | @see ErrorType |
347 | */ |
348 | void ( KBlog::Blog::ErrorType type, |
349 | const QString &errorMessage, KBlog::BlogPost *post, |
350 | KBlog::BlogComment * ); |
351 | |
352 | protected: |
353 | /** A pointer to the corresponding 'Private' class */ |
354 | BlogPrivate *const d_ptr; |
355 | |
356 | /** |
357 | Constructor needed to allow private inheritance of 'Private' classes. |
358 | |
359 | @param server URL for the blog's XML-RPC interface. |
360 | @param dd URL for the corresponding private class. |
361 | @param parent the parent of this object, defaults to null. |
362 | @param applicationName the client application's name to use in the |
363 | HTTP user agent string, defaults to KBlog's own. |
364 | @param applicationVersion the client application's version to use in the |
365 | HTTP user agent string, defaults to KBlog's own. |
366 | */ |
367 | Blog( const KUrl &server, BlogPrivate &dd, QObject *parent = 0, |
368 | const QString &applicationName = QString(), |
369 | const QString &applicationVersion = QString() ); |
370 | |
371 | private: |
372 | Q_DECLARE_PRIVATE( Blog ) |
373 | }; |
374 | |
375 | } //namespace KBlog |
376 | #endif |
377 | |