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