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
31template <class T,class S> class QMap;
32
33class KTimeZone;
34class 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. */
53namespace KBlog {
54
55class BlogPost;
56class BlogComment;
57class BlogMedia;
58class 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
71class 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 errorComment( KBlog::Blog::ErrorType type,
349 const QString &errorMessage, KBlog::BlogPost *post,
350 KBlog::BlogComment *comment );
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