File: provider.h

package info (click to toggle)
attica 0.2.0-1
  • links: PTS, VCS
  • area: main
  • in suites: wheezy
  • size: 644 kB
  • sloc: cpp: 5,227; makefile: 3
file content (478 lines) | stat: -rw-r--r-- 17,735 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
/*
    This file is part of KDE.

    Copyright (c) 2008 Cornelius Schumacher <schumacher@kde.org>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2.1 of the License, or (at your option) version 3, or any
    later version accepted by the membership of KDE e.V. (or its
    successor approved by the membership of KDE e.V.), which shall
    act as a proxy defined in Section 6 of version 3 of the license.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library.  If not, see <http://www.gnu.org/licenses/>.

*/

#ifndef ATTICA_PROVIDER_H
#define ATTICA_PROVIDER_H

#include <QtCore/QExplicitlySharedDataPointer>
#include <QtCore/QSharedPointer>
#include <QtCore/QString>

#include <QtCore/QUrl>

#include "atticaclient_export.h"
#include "category.h"
#include "itemjob.h"
#include "listjob.h"
#include "message.h"
#include "comment.h"
#include "distribution.h"
#include "license.h"

class QDate;
class QUrl;

namespace Attica {

class PlatformDependent;

class PostJobStatus;

class AccountBalance;
class Activity;
class PrivateData;
class Content;
class DownloadItem;
class Distribution;
class Event;
class Folder;
class HomePageType;
class KnowledgeBaseEntry;
class License;
class Person;
class PostJob;
class Provider;


/**
 * The Provider class represents one Open Collaboration Service provider.
 * Use the ProviderManager to instanciate a Provider.
 *
 * Accessing functions of the Provider returns a Job class that
 * takes care of accessing the server and parsing the result.
 *
 * Provider files are xml of the form:
 <pre>
 <provider>
 <id>opendesktop</id>
 <location>https://api.opendesktop.org/v1/</location>
 <name>openDesktop.org</name>
 <icon></icon>
 <termsofuse>https://opendesktop.org/terms/</termsofuse>
 <register>https://opendesktop.org/usermanager/new.php</register>
 <services>
   <person ocsversion="1.3" />
   <friend ocsversion="1.3" />
   <message ocsversion="1.3" />
   <activity ocsversion="1.3" />
   <content ocsversion="1.3" />
   <fan ocsversion="1.3" />
   <knowledgebase ocsversion="1.3" />
   <event ocsversion="1.3" />
   <comment ocsversion="1.2" />
 </services>
</provider>
 </pre>
 * The server provides the services specified in the services section, not necessarily all of them. 
 */
class ATTICA_EXPORT Provider
{
  public:
    Provider();
    Provider(const Provider& other);
    Provider& operator=(const Provider& other);
    ~Provider();

    /**
    Returns true if the provider has been set up and can be used.
    */
    bool isValid() const;
    
    /**
    Test if the provider is enabled by the settings.
    The application can choose to ignore this, but the user settings should be respected.
    */
    bool isEnabled() const;
    void setEnabled(bool enabled);
    
    /**
    A url that identifies this provider.
    This should be used as identifier when refering to this provider but you don't want to use the full provider object.
    */
    QUrl baseUrl() const;
    
    /**
    A name for the provider that can be displayed to the user
    */
    QString name() const;

    enum SortMode {
        Newest,
        Alphabetical,
        Rating,
        Downloads
    };

    /**
    Test if the server supports the person part of the API
    */
    bool hasPersonService() const;
    /**
    Version of the person part of the API
    */
    QString personServiceVersion() const;
    
    /**
    Test if the server supports the friend part of the API
    */
    bool hasFriendService() const;
    
    /**
    Version of the friend part of the API
    */
    QString friendServiceVersion() const;
    
    /**
    Test if the server supports the message part of the API
    */
    bool hasMessageService() const;
    /**
    Version of the message part of the API
    */
    QString messageServiceVersion() const;
    
    /**
    Test if the server supports the activity part of the API
    */
    bool hasActivityService() const;
    /**
    Version of the activity part of the API
    */
    QString activityServiceVersion() const;
    
    /**
    Test if the server supports the content part of the API
    */
    bool hasContentService() const;
    /**
    Version of the content part of the API
    */
    QString contentServiceVersion() const;
    
    /**
    Test if the server supports the fan part of the API
    */
    bool hasFanService() const;
    /**
    Version of the fan part of the API
    */
    QString fanServiceVersion() const;
    
    /**
    Test if the server supports the knowledgebase part of the API
    */
    bool hasKnowledgebaseService() const;
    /**
    Version of the knowledgebase part of the API
    */
    QString knowledgebaseServiceVersion() const;
    
    /**
    Test if the server supports the comments part of the API
    */
    bool hasCommentService() const;
    /**
    Version of the comments part of the API
    */
    QString commentServiceVersion() const;

    /**
      Test if the provider has user name/password available.
      This does not yet open kwallet in case the KDE plugin is used.
      @return true if the provider has login information
    */
    bool hasCredentials() const;
    bool hasCredentials();
    
    /**
      Load user name and password from the store.
      Attica will remember the loaded values and use them from this point on.
      @param user reference that returns the user name
      @param password reference that returns the password
      @return if credentials could be loaded
    */
    bool loadCredentials(QString& user, QString& password);
    
    /**
      Sets (and remembers) user name and password for this provider.
      To remove the data an empty username should be passed.
      @param user the user (login) name
      @param password the password
      @return if credentials could be saved
    */
    bool saveCredentials(const QString& user, const QString& password);
    
    /**
      Test if the server accepts the login/password.
      This function does not actually set the credentials. Use saveCredentials for that purpose.
      @param user the user (login) name
      @param password the password
      @return the job that will contain the success of the login as metadata
    */
    PostJob* checkLogin(const QString& user, const QString& password);

    // Person part of OCS

    PostJob* registerAccount(const QString& id, const QString& password, const QString& mail, const QString& firstName, const QString& lastName);
    ItemJob<Person>* requestPerson(const QString& id);
    ItemJob<Person>* requestPersonSelf();
    ItemJob<AccountBalance>* requestAccountBalance();
    ListJob<Person>* requestPersonSearchByName(const QString& name);
    ListJob<Person>* requestPersonSearchByLocation(qreal latitude, qreal longitude, qreal distance = 0.0, int page = 0, int pageSize = 20);
    PostJob* postLocation(qreal latitude, qreal longitude, const QString& city = QString(), const QString& country = QString());

    //////////////////////////
    // PrivateData part of OCS

    /**
     * Fetches the a given attribute from an OCS-compliant server.
     * @param app The application name
     * @param key The key of the attribute to fetch (optional)
     * @return The job that is responsible for fetching the data
     */
    ItemJob<PrivateData>* requestPrivateData(const QString& app, const QString& key = QString());

    /**
     * Fetches all stored private data.
     * @return The job responsible for fetching data
     */
    ItemJob<PrivateData>* requestPrivateData() { return requestPrivateData(QString(), QString()); }

    /**
     * Sets the value of an attribute.
     * @param app The application name
     * @param key The key of the attribute
     * @param value The new value of the attribute
     * @return The job responsible for setting data
     */
    PostJob* setPrivateData(const QString &app, const QString &key, const QString &value);

    // Friend part of OCS

    ListJob<Person>* requestFriends(const QString& id, int page = 0, int pageSize = 20);
    PostJob* postFriendInvitation(const QString& to, const QString& message);
    ListJob<Person>* requestSentInvitations(int page = 0, int pageSize = 20);
    ListJob<Person>* requestReceivedInvitations(int page = 0, int pageSize = 20);
    PostJob* inviteFriend(const QString& to, const QString& message);
    PostJob* approveFriendship(const QString& to);
    PostJob* declineFriendship(const QString& to);
    PostJob* cancelFriendship(const QString& to);

    // Message part of OCS

    ListJob<Folder>* requestFolders();
    ListJob<Message>* requestMessages(const Folder& folder);
    ListJob<Message>* requestMessages(const Folder& folder, Message::Status status);
    ItemJob<Message>* requestMessage(const Folder& folder, const QString& id);
    PostJob* postMessage(const Message& message);

    // Activity part of OCS

    ListJob<Activity>* requestActivities();
    PostJob* postActivity(const QString& message);

    // Content part of OCS

    /** 
     * Get a list of categories (such as wallpaper)
     * @return the categories of the server
     */
    ListJob<Category>* requestCategories();
    
    /** 
    * Get a list of licenses (such as GPL)
    * @return the licenses available from the server
    */
    ListJob<License>* requestLicenses();

    /**
    * Get a list of distributions (such as Ark, Debian)
    * @return the licenses available from the server
    */
    ListJob<Distribution>* requestDistributions();

    /**
    * Get a list of home page types (such as blog, Facebook)
    * @return the licenses available from the server
    */
    ListJob<HomePageType>* requestHomePageTypes();

    /**
      Request a list of Contents.
      Note that @p categories is not optional. If left empty, no results will be returned.
      An empty search string @p search returns the top n items.
      @param categories categories to search in
      @param search optional search string (in name/description of the content)
      @param mode sorting mode
      @param page request nth page in the list of results
      @param pageSize requested size of pages when calculating the list of results
      @return list job for the search results
      */
    ListJob<Content>* searchContents(const Category::List& categories, const QString& search = QString(), SortMode mode = Rating, uint page = 0, uint pageSize = 10);

    /**
      Request a list of Contents.
      Like @see searchContents, but only contents created by one person.
      @param person the person-id that created the contents.
     */
    ListJob<Content>* searchContentsByPerson(const Category::List& categories, const QString& person, const QString& search = QString(), SortMode mode = Rating, uint page = 0, uint pageSize = 10);

    /**
      Request a list of Contents. More complete version.
      Note that @p categories is not optional. If left empty, no results will be returned.
      An empty search string @p search returns the top n items.
      @param categories categories to search in
      @param person the person-id that created the contents
      @param distributions list of distributions to filter by, if empty no filtering by distribution is done
      @param licenses list of licenses to filter by, if empty no filtering by license is done
      @param search optional search string (in name/description of the content)
      @param mode sorting mode
      @param page request nth page in the list of results
      @param pageSize requested size of pages when calculating the list of results
      @return list job for the search results
      */
    ListJob<Content>* searchContents(const Category::List& categories, const QString& person, const Distribution::List& distributions, const License::List& licenses, const QString& search = QString(), SortMode sortMode = Rating, uint page = 0, uint pageSize = 10);

    /**
      Retrieve a single content.
      @param contentId the id of the content
      @return job that retrieves the content object
     */
    ItemJob<Content>* requestContent(const QString& contentId);

    ItemJob<DownloadItem>* downloadLink(const QString& contentId, const QString& itemId = QLatin1String("1"));

    /** Vote for a content item
     * This version is for the old OCS API < 1.6
     * @param contentId the content which this voting is for
     * @param positiveVote whether the voting is positive or negative
     * @return the post job for this voting
     */
    Q_DECL_DEPRECATED PostJob* voteForContent(const QString& contentId, bool positiveVote);

    /** Vote for a content item
     * @param contentId the content which this voting is for
     * @param rating - the rating, must be between 0 (bad) and 100 (good)
     * @return the post job for this voting
     */
    PostJob* voteForContent(const QString& contentId, uint rating);

    ItemPostJob<Content>* addNewContent(const Category& category, const Content& newContent);
    ItemPostJob<Content>* editContent(const Category& updatedCategory, const QString& contentId, const Content& updatedContent);
    PostJob* deleteContent(const QString& contentId);

    PostJob* setDownloadFile(const QString& contentId, const QString& fileName, QIODevice* payload);
    PostJob* setDownloadFile(const QString& contentId, const QString& fileName, const QByteArray& payload);
    PostJob* deleteDownloadFile(const QString& contentId);

    /**
     * Upload an image file as preview for the content
     * @param contentId
     * @param previewId each content can have previews with the id 1,2 or 3
     * @param payload the image file
     */
    PostJob* setPreviewImage(const QString& contentId, const QString& previewId, const QString& fileName, const QByteArray& image);
    PostJob* deletePreviewImage(const QString& contentId, const QString& previewId);

    // KnowledgeBase part of OCS

    ItemJob<KnowledgeBaseEntry>* requestKnowledgeBaseEntry(const QString& id);
    ListJob<KnowledgeBaseEntry>* searchKnowledgeBase(const Content& content, const QString& search, SortMode, int page, int pageSize);

    // Event part of OCS

    ItemJob<Event>* requestEvent(const QString& id);
    ListJob<Event>* requestEvent(const QString& country, const QString& search, const QDate& startAt, SortMode mode, int page, int pageSize);

    // Comment part of OCS
    /** Request a list of comments for a content / forum / knowledgebase / event.
     * @param comment::Type type of the comment @see Comment::Type (content / forum / knowledgebase / event)
     * @param id id of the content entry where you want to get the comments is from
     * @param id2 id of the content entry where you want to get the comments is from
     * @param page request nth page in the list of results
     * @param pageSize requested size of pages when calculating the list of results
     * @return list job for the comments results
     */
    ListJob<Comment>* requestComments(const Comment::Type commentType, const QString& id, const QString& id2, int page, int pageSize);

    /** Add a new comment.
     * @param commentType type of the comment @see CommentType (content / forum / knowledgebase / event)
     * @param id id of the content entry where you want to get the comments is from
     * @param id2 id of the sub content entry where you want to get the comments is from
     * @param parentId the id of the parent comment if the new comment is a reply
     * @param subject title of the comment
     * @param message text of the comment
     * @return item post job for adding the new comment
     */
    ItemPostJob<Comment>* addNewComment(const Comment::Type commentType, const QString& id, const QString& id2, const QString& parentId, const QString &subject, const QString& message);

    /** Vote a comment item
     * @param id the comment id which this voting is for
     * @param rating the rating, must be between 0 (bad) and 100 (good)
     * @return the post job for this voting
     */
    PostJob* voteForComment(const QString & id, uint rating);

    // Fan part of OCS

    PostJob* becomeFan(const QString& contentId);
    ListJob<Person>* requestFans(const QString& contentId, uint page = 0, uint pageSize = 10);

  protected:
    QUrl createUrl(const QString& path);
    QNetworkRequest createRequest(const QUrl& url);
    // Convenience overload
    QNetworkRequest createRequest(const QString& path);

    ItemJob<Person>* doRequestPerson(const QUrl& url);
    ItemJob<AccountBalance>* doRequestAccountBalance(const QUrl& url);
    ListJob<Person>* doRequestPersonList(const QUrl& url);
    ListJob<Activity>* doRequestActivityList(const QUrl& url);
    ListJob<Folder>* doRequestFolderList(const QUrl& url);
    ListJob<Message>* doRequestMessageList(const QUrl& url);

  private:
    class Private;
    QExplicitlySharedDataPointer<Private> d;
    
    Provider(PlatformDependent* internals, const QUrl& baseUrl, const QString& name, const QUrl& icon = QUrl());
    Provider(PlatformDependent* internals, const QUrl& baseUrl, const QString& name, const QUrl& icon,
             const QString& person, const QString& friendV, const QString& message,
             const QString& activity, const QString& content, const QString& fan,
             const QString& knowledgebase, const QString& event, const QString& comment);

friend class ProviderManager;
};
}

#endif