1 /*
2     SPDX-FileCopyrightText: 2006 Volker Krause <vkrause@kde.org>
3 
4     SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include "akonadicore_export.h"
10 #include "job.h"
11 
12 namespace Akonadi
13 {
14 class CachePolicy;
15 class Collection;
16 class CollectionModifyJobPrivate;
17 
18 /**
19  * @short Job that modifies a collection in the Akonadi storage.
20  *
21  * This job modifies the properties of an existing collection.
22  *
23  * @code
24  *
25  * Akonadi::Collection collection = ...
26  *
27  * Akonadi::CollectionModifyJob *job = new Akonadi::CollectionModifyJob( collection );
28  * connect( job, SIGNAL(result(KJob*)), this, SLOT(modifyResult(KJob*)) );
29  *
30  * @endcode
31  *
32  * If the collection has attributes, it is recommended only to supply values for
33  * any attributes whose values are to be updated. This will help to avoid
34  * potential clashes with other resources or applications which may happen to
35  * update the collection simultaneously. To avoid supplying attribute values which
36  * are not needed, create a new instance of the collection and explicitly set
37  * attributes to be updated, e.g.
38  *
39  * @code
40  *
41  * // Update the 'MyAttribute' attribute of 'collection'.
42  * Akonadi::Collection c( collection.id() );
43  * MyAttribute *attribute = c.attribute<MyAttribute>( Collection::AddIfMissing );
44  * if ( collection.hasAttribute<MyAttribute>() ) {
45  *     *attribute = *collection.attribute<MyAttribute>();
46  * }
47  * // Update the value of 'attribute' ...
48  * Akonadi::CollectionModifyJob *job = new Akonadi::CollectionModifyJob( c );
49  * connect( job, SIGNAL(result(KJob*)), this, SLOT(modifyResult(KJob*)) );
50  *
51  * @endcode
52  *
53  * To update only the collection, and not change any attributes:
54  *
55  * @code
56  *
57  * // Update the cache policy for 'collection' to 'newPolicy'.
58  * Akonadi::Collection c( collection.id() );
59  * c.setCachePolicy( newPolicy );
60  * Akonadi::CollectionModifyJob *job = new Akonadi::CollectionModifyJob( c );
61  * connect( job, SIGNAL(result(KJob*)), this, SLOT(modifyResult(KJob*)) );
62  *
63  * @endcode
64  *
65  * @author Volker Krause <vkrause@kde.org>
66  */
67 class AKONADICORE_EXPORT CollectionModifyJob : public Job
68 {
69     Q_OBJECT
70 
71 public:
72     /**
73      * Creates a new collection modify job for the given collection. The collection can be
74      * identified either by its unique identifier or its remote identifier. Since the remote
75      * identifier is not necessarily globally unique, identification by remote identifier only
76      * works inside a resource context (that is from within ResourceBase) and is therefore
77      * limited to one resource.
78      *
79      * @param collection The collection to modify.
80      * @param parent The parent object.
81      */
82     explicit CollectionModifyJob(const Collection &collection, QObject *parent = nullptr);
83 
84     /**
85      * Destroys the collection modify job.
86      */
87     ~CollectionModifyJob() override;
88 
89     /**
90      * Returns the modified collection.
91      *
92      * @since 4.4
93      */
94     Q_REQUIRED_RESULT Collection collection() const;
95 
96 protected:
97     void doStart() override;
98     bool doHandleResponse(qint64 tag, const Protocol::CommandPtr &response) override;
99 
100 private:
101     Q_DECLARE_PRIVATE(CollectionModifyJob)
102 };
103 
104 }
105 
106