Akonadi

collectionmodifyjob.h
1 /*
2  SPDX-FileCopyrightText: 2006 Volker Krause <[email protected]>
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 <[email protected]>
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 }
Job that modifies a collection in the Akonadi storage.
Represents a collection of PIM items.
Definition: collection.h:61
Base class for all actions in the Akonadi storage.
Definition: job.h:80
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Sep 30 2023 04:01:51 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.