1/*
2 Copyright (c) 2009 Constantin Berzan <exit3219@gmail.com>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef AKONADI_SPECIALCOLLECTIONSREQUESTJOB_H
21#define AKONADI_SPECIALCOLLECTIONSREQUESTJOB_H
22
23#include "akonadi_export.h"
24
25#include <akonadi/collection.h>
26#include <akonadi/specialcollections.h>
27#include <akonadi/transactionsequence.h>
28
29#include <QtCore/QVariant>
30
31namespace Akonadi {
32
33class SpecialCollectionsRequestJobPrivate;
34
35/**
36 * @short A job to request SpecialCollections.
37 *
38 * Use this job to request the SpecialCollections you need. You can request both
39 * default SpecialCollections and SpecialCollections in a given resource. The default
40 * SpecialCollections resource is created when the first default SpecialCollection is
41 * requested, but if a SpecialCollection in a custom resource is requested, this
42 * job expects that resource to exist already.
43 *
44 * If the folders you requested already exist, this job simply succeeds.
45 * Otherwise, it creates the required collections and registers them with
46 * SpecialCollections.
47 *
48 * This class is not meant to be used directly but as a base class for type
49 * specific special collection request jobs.
50 *
51 * @author Constantin Berzan <exit3219@gmail.com>
52 * @since 4.4
53*/
54class AKONADI_EXPORT SpecialCollectionsRequestJob : public TransactionSequence
55{
56 Q_OBJECT
57
58public:
59
60 /**
61 * Destroys the special collections request job.
62 */
63 ~SpecialCollectionsRequestJob();
64
65 /**
66 * Requests a special collection of the given @p type in the default resource.
67 */
68 void requestDefaultCollection(const QByteArray &type);
69
70 /**
71 * Requests a special collection of the given @p type in the given resource @p instance.
72 */
73 void requestCollection(const QByteArray &type, const AgentInstance &instance);
74
75 /**
76 * Returns the requested collection.
77 */
78 Collection collection() const;
79
80protected:
81 /**
82 * Creates a new special collections request job.
83 *
84 * @param collections The SpecialCollections object that shall be used.
85 * @param parent The parent object.
86 */
87 explicit SpecialCollectionsRequestJob(SpecialCollections *collections, QObject *parent = 0);
88
89 /**
90 * Sets the @p type of the resource that shall be created if the requested
91 * special collection does not exist yet.
92 */
93 void setDefaultResourceType(const QString &type);
94
95 /**
96 * Sets the configuration @p options that shall be applied to the new resource
97 * that is created if the requested special collection does not exist yet.
98 */
99 void setDefaultResourceOptions(const QVariantMap &options);
100
101 /**
102 * Sets the list of well known special collection @p types.
103 */
104 void setTypes(const QList<QByteArray> &types);
105
106 /**
107 * Sets the @p map of special collection types to display names.
108 */
109 void setNameForTypeMap(const QMap<QByteArray, QString> &map);
110
111 /**
112 * Sets the @p map of special collection types to icon names.
113 */
114 void setIconForTypeMap(const QMap<QByteArray, QString> &map);
115
116 /* reimpl */
117 virtual void doStart();
118 /* reimpl */
119 virtual void slotResult(KJob *job);
120
121private:
122 //@cond PRIVATE
123 friend class SpecialCollectionsRequestJobPrivate;
124 friend class DefaultResourceJobPrivate;
125
126 SpecialCollectionsRequestJobPrivate *const d;
127
128 Q_PRIVATE_SLOT(d, void lockResult(KJob *))
129 Q_PRIVATE_SLOT(d, void releaseLock())
130 Q_PRIVATE_SLOT(d, void resourceScanResult(KJob *))
131 Q_PRIVATE_SLOT(d, void collectionCreateResult(KJob *))
132 //@endcond
133};
134
135} // namespace Akonadi
136
137#endif // AKONADI_SPECIALCOLLECTIONSREQUESTJOB_H
138