1 /*
2     SPDX-FileCopyrightText: 2009 Constantin Berzan <exit3219@gmail.com>
3 
4     SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include "akonadicore_export.h"
10 #include "collection.h"
11 #include "specialcollections.h"
12 #include "transactionsequence.h"
13 
14 #include <QVariant>
15 
16 #include <memory>
17 
18 namespace Akonadi
19 {
20 class SpecialCollectionsRequestJobPrivate;
21 
22 /**
23  * @short A job to request SpecialCollections.
24  *
25  * Use this job to request the SpecialCollections you need. You can request both
26  * default SpecialCollections and SpecialCollections in a given resource. The default
27  * SpecialCollections resource is created when the first default SpecialCollection is
28  * requested, but if a SpecialCollection in a custom resource is requested, this
29  * job expects that resource to exist already.
30  *
31  * If the folders you requested already exist, this job simply succeeds.
32  * Otherwise, it creates the required collections and registers them with
33  * SpecialCollections.
34  *
35  * This class is not meant to be used directly but as a base class for type
36  * specific special collection request jobs.
37  *
38  * @author Constantin Berzan <exit3219@gmail.com>
39  * @since 4.4
40  */
41 class AKONADICORE_EXPORT SpecialCollectionsRequestJob : public TransactionSequence
42 {
43     Q_OBJECT
44 
45 public:
46     /**
47      * Destroys the special collections request job.
48      */
49     ~SpecialCollectionsRequestJob() override;
50 
51     /**
52      * Requests a special collection of the given @p type in the default resource.
53      */
54     void requestDefaultCollection(const QByteArray &type);
55 
56     /**
57      * Requests a special collection of the given @p type in the given resource @p instance.
58      */
59     void requestCollection(const QByteArray &type, const AgentInstance &instance);
60 
61     /**
62      * Returns the requested collection.
63      */
64     Q_REQUIRED_RESULT Collection collection() const;
65 
66 protected:
67     /**
68      * Creates a new special collections request job.
69      *
70      * @param collections The SpecialCollections object that shall be used.
71      * @param parent The parent object.
72      */
73     explicit SpecialCollectionsRequestJob(SpecialCollections *collections, QObject *parent = nullptr);
74 
75     /**
76      * Sets the @p type of the resource that shall be created if the requested
77      * special collection does not exist yet.
78      */
79     void setDefaultResourceType(const QString &type);
80 
81     /**
82      * Sets the configuration @p options that shall be applied to the new resource
83      * that is created if the requested special collection does not exist yet.
84      */
85     void setDefaultResourceOptions(const QVariantMap &options);
86 
87     /**
88      * Sets the list of well known special collection @p types.
89      */
90     void setTypes(const QList<QByteArray> &types);
91 
92     /**
93      * Sets the @p map of special collection types to display names.
94      */
95     void setNameForTypeMap(const QMap<QByteArray, QString> &map);
96 
97     /**
98      * Sets the @p map of special collection types to icon names.
99      */
100     void setIconForTypeMap(const QMap<QByteArray, QString> &map);
101 
102     /* reimpl */
103     void doStart() override;
104     /* reimpl */
105     void slotResult(KJob *job) override;
106 
107 private:
108     /// @cond PRIVATE
109     friend class SpecialCollectionsRequestJobPrivate;
110     friend class DefaultResourceJobPrivate;
111 
112     std::unique_ptr<SpecialCollectionsRequestJobPrivate> const d;
113 
114     Q_PRIVATE_SLOT(d, void releaseLock())
115     Q_PRIVATE_SLOT(d, void resourceScanResult(KJob *))
116     Q_PRIVATE_SLOT(d, void collectionCreateResult(KJob *))
117     /// @endcond
118 };
119 
120 } // namespace Akonadi
121 
122