1/*
2 This file is part of the kblog library.
3
4 Copyright (c) 2007 Christian Weilbach <christian_weilbach@web.de>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21
22#ifndef KBLOG_GDATA_H
23#define KBLOG_GDATA_H
24
25#include <kblog/blog.h>
26#include <kdatetime.h>
27
28#include <QtCore/QStringList>
29
30class KUrl;
31
32/**
33 @file
34
35 This file is part of the for accessing Blog Servers
36 and defines the GData class.
37
38 @author Reinhold Kainhofer \<reinhold\@kainhofer.com\>
39
40 \par Maintainer: Christian Weilbach \<christian_weilbach\@web.de\>
41 */
42
43namespace KBlog {
44
45 class GDataPrivate;
46 class BlogComment;
47
48/**
49 @brief
50 A class that can be used for access to GData blogs. The new blogspot.com
51 accounts ( August 2007 ) exclusively support GData API which is a standard
52 based on Atom API. Compared to Blogger 1.0, which is based on Xml-Rpc and
53 less secure, it adds new functionality like titles and comments.
54
55 @code
56 Blog* myblog = new GData("http://myblogspot.account.com");
57 myblog->setProfileId( "2039484587348593945823" ); // can be fetched via fetchProfileId()
58 myblog->setBlogId( "1" ); // can be caught by listBlogs()
59 myblog->setUsername( "your_email@address.com" );
60 myblog->setPassword( "yOuRFuNnYPasSword" );
61 KBlog::BlogPost *post = new BlogPost();
62 post->setTitle( "This is the title." );
63 post->setContent( "Here is some the content..." );
64 myblog->createPost( post );
65 @endcode
66
67 @author Christian Weilbach \<christian_weilbach\@web.de\>
68 @author Reinhold Kainhofer \<reinhold\@kainhofer.com\>
69 */
70class KBLOG_EXPORT GData : public Blog
71{
72 Q_OBJECT
73 public:
74 /**
75 Create an object for GData
76 @param server The server url for the xmlrpc gateway.
77 @param parent The parent object, inherited from QObject.
78 */
79 explicit GData( const KUrl &server, QObject *parent = 0 );
80
81 /**
82 Destructor.
83 */
84 ~GData();
85
86 /**
87 Sets the user's name for the blog. Username is only the E-Mail
88 address of the user. This is used in createPost and modifyPost.
89 @param fullName is a QString containing the blog username.
90
91 @see username()
92 @see createPost( KBlog::BlogPost* )
93 @see modifiyPost( KBlog::BlogPost* )
94 */
95 virtual void setFullName( const QString &fullName );
96
97 /**
98 Returns the full name of user of the blog.
99 @see setFullName()
100 */
101 QString fullName() const;
102
103 /**
104 Returns the profile id of the blog. This is used for rss paths internally.
105 @return The profile id.
106
107 @see setProfileId( const QString& )
108 */
109 QString profileId() const;
110
111 /**
112 Get the profile's id of the blog.
113 @param pid This is nummeric id.
114
115 @see profileId()
116 */
117 virtual void setProfileId( const QString &pid );
118
119 /**
120 Returns the of the inherited object.
121 */
122 QString interfaceName() const;
123
124 /**
125 Get information about the profile from the blog.
126 Sets the profileId automatically for the blog it is called from.
127
128 @see setProfileId( const QString& )
129 @see void fetchedProfileId( const QString& )
130 */
131 void fetchProfileId();
132
133 /**
134 List the blogs available for this authentication on the server.
135
136 @see void listedBlogs( const QList\<QMap\<QString,QString\>\>& )
137 */
138 virtual void listBlogs();
139
140 /**
141 List the comments available for this post on the server.
142 @param post The post, which posts should be listed.
143
144 @see void listedComments( KBlog::BlogPost*, const QList\<KBlog::BlogComment\>& )
145 */
146 virtual void listComments( KBlog::BlogPost *post );
147
148 /**
149 List the all comments available for this authentication on the server.
150
151 @see void listedAllComments( const QList\<KBlog::BlogComment\>& )
152 */
153 virtual void listAllComments();
154
155 /**
156 List recent posts on the server. The status of the posts will be Fetched.
157 @param number The number of posts to fetch. The order is newest first.
158
159 @see void listedPosts( const QList\<KBlog::BlogPost\>& )
160 @see void fetchPost( KBlog::BlogPost* )
161 @see BlogPost::Status
162 */
163 void listRecentPosts( int number );
164
165 /**
166 List recent posts on the server depending on meta information about the post.
167 @param label The lables of posts to fetch.
168 @param number The number of posts to fetch. The order is newest first.
169 @param upMinTime The oldest upload time of the posts to fetch.
170 @param upMaxTime The newest upload time of the posts to fetch.
171 @param pubMinTime The oldest publication time of the posts to fetch.
172 @param pubMaxTime The newest publication time of the posts to fetch.
173
174 @see void listedPosts( const QList\<KBlog::BlogPost\>& )
175 @see void fetchPost( KBlog::BlogPost* )
176 */
177 virtual void listRecentPosts( const QStringList &label=QStringList(), int number=0,
178 const KDateTime &upMinTime=KDateTime(),
179 const KDateTime &upMaxTime=KDateTime(),
180 const KDateTime &pubMinTime=KDateTime(),
181 const KDateTime &pubMaxTime=KDateTime() );
182
183 /**
184 Fetch the Post with a specific id.
185 @param post This is the post with its id set correctly.
186
187 @see BlogPost::setPostId( const QString& )
188 @see fetchedPost( KBlog::BlogPost *post )
189 */
190 void fetchPost( KBlog::BlogPost *post );
191
192 /**
193 Modify a post on server.
194 @param post This is used to send the modified post including the correct id.
195 */
196 void modifyPost( KBlog::BlogPost *post );
197
198 /**
199 Create a new post on server.
200 @param post This is send to the server.
201
202 @see createdPost( KBlog::BlogPost *post )
203 */
204 void createPost( KBlog::BlogPost *post );
205
206 /**
207 Remove a post from the server.
208 @param post This is the post with its id set correctly.
209
210 @see BlogPost::setPostId( const QString& )
211 @see removedPost( KBlog::BlogPost* )
212 */
213 void removePost( KBlog::BlogPost *post );
214
215 /**
216 Create a comment on the server.
217 @param post This is the post with its id set correctly.
218 @param comment This is the comment to create.
219
220 @see BlogPost::setPostId( const QString& )
221 @see createdComment( KBlog::BlogPost*, KBlog::BlogComment* )
222 */
223 virtual void createComment( KBlog::BlogPost *post, KBlog::BlogComment *comment );
224
225 /**
226 Remove a comment from the server.
227 @param post This is the post with its id set correctly.
228 @param comment This is the comment to remove.
229
230 @see BlogPost::setPostId( const QString& )
231 @see removedComment( KBlog::BlogPost*, KBlog::BlogComment* )
232 */
233 virtual void removeComment( KBlog::BlogPost *post, KBlog::BlogComment *comment );
234
235 Q_SIGNALS:
236
237 /**
238 This signal is emitted when a list of blogs has been fetched
239 from the blogging server.
240 @param blogsList The list of blogs.
241
242 @see listBlogs()
243 */
244 void listedBlogs( const QList<QMap<QString,QString> >& blogsList );
245
246 /**
247 This signal is emitted when a list of all comments has been
248 fetched from the blogging server.
249 @param commentsList The list of comments.
250
251 @see listAllComments()
252 */
253 void listedAllComments( const QList<KBlog::BlogComment> &commentsList );
254
255 /**
256 This signal is emitted when a list of comments has been fetched
257 from the blogging server.
258 @param post This is the corresponding post.
259 @param comments The list of comments.
260
261 @see listComments( KBlog::BlogPost* )
262 */
263 void listedComments( KBlog::BlogPost *post, const QList<KBlog::BlogComment> &comments );
264
265 /**
266 This signal is emitted when a comment has been created
267 on the blogging server.
268 @param post This is the corresponding post.
269 @param comment This is the created comment.
270
271 @see createComment( KBlog::BlogPost *post, KBlog::BlogComment *comment )
272 */
273 void createdComment( const KBlog::BlogPost *post, const KBlog::BlogComment *comment );
274
275 /**
276 This signal is emitted when a comment has been removed
277 from the blogging server.
278 @param post This is the corresponding post.
279 @param comment This is the removed comment.
280
281 @see removeComment( KBlog::BlogPost *post, KBlog::BlogComment *comment )
282 */
283 void removedComment( const KBlog::BlogPost *post, const KBlog::BlogComment *comment );
284
285 /**
286 This signal is emitted when the profile id has been
287 fetched.
288 @param profileId This is the fetched id. On error it is QString()
289
290 @see fetchProfileId()
291 */
292 void fetchedProfileId( const QString &profileId );
293
294 protected:
295 /**
296 Overloaded for private inheritance handling.
297 */
298 GData( const KUrl &server, GDataPrivate &dd, QObject *parent = 0 );
299
300 private:
301 Q_DECLARE_PRIVATE( GData )
302 Q_PRIVATE_SLOT( d_func(),
303 void slotFetchProfileId( KJob * ) )
304 Q_PRIVATE_SLOT( d_func(),
305 void slotListBlogs( Syndication::Loader *,
306 Syndication::FeedPtr, Syndication::ErrorCode ) )
307 Q_PRIVATE_SLOT( d_func(),
308 void slotListComments( Syndication::Loader *,
309 Syndication::FeedPtr, Syndication::ErrorCode ) )
310 Q_PRIVATE_SLOT( d_func(),
311 void slotListAllComments( Syndication::Loader *,
312 Syndication::FeedPtr, Syndication::ErrorCode ) )
313 Q_PRIVATE_SLOT( d_func(),
314 void slotListRecentPosts( Syndication::Loader *,
315 Syndication::FeedPtr, Syndication::ErrorCode ) )
316 Q_PRIVATE_SLOT( d_func(),
317 void slotFetchPost( Syndication::Loader *,
318 Syndication::FeedPtr, Syndication::ErrorCode ) )
319 Q_PRIVATE_SLOT( d_func(),
320 void slotCreatePost( KJob * ) )
321 Q_PRIVATE_SLOT( d_func(),
322 void slotModifyPost( KJob * ) )
323 Q_PRIVATE_SLOT( d_func(),
324 void slotRemovePost( KJob * ) )
325 Q_PRIVATE_SLOT( d_func(),
326 void slotCreateComment( KJob * ) )
327 Q_PRIVATE_SLOT( d_func(),
328 void slotRemoveComment( KJob * ) )
329};
330
331} //namespace KBlog
332#endif
333