1/*
2 Copyright (c) 2006 Volker Krause <vkrause@kde.org>
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_COLLECTIONMODIFYJOB_H
21#define AKONADI_COLLECTIONMODIFYJOB_H
22
23#include "akonadi_export.h"
24
25#include <akonadi/job.h>
26
27namespace Akonadi {
28
29class CachePolicy;
30class Collection;
31class CollectionModifyJobPrivate;
32
33/**
34 * @short Job that modifies a collection in the Akonadi storage.
35 *
36 * This job modifies the properties of an existing collection.
37 *
38 * @code
39 *
40 * Akonadi::Collection collection = ...
41 *
42 * Akonadi::CollectionModifyJob *job = new Akonadi::CollectionModifyJob( collection );
43 * connect( job, SIGNAL(result(KJob*)), this, SLOT(modifyResult(KJob*)) );
44 *
45 * @endcode
46 *
47 * If the collection has attributes, it is recommended only to supply values for
48 * any attributes whose values are to be updated. This will help to avoid
49 * potential clashes with other resources or applications which may happen to
50 * update the collection simultaneously. To avoid supplying attribute values which
51 * are not needed, create a new instance of the collection and explicitly set
52 * attributes to be updated, e.g.
53 *
54 * @code
55 *
56 * // Update the 'MyAttribute' attribute of 'collection'.
57 * Akonadi::Collection c( collection.id() );
58 * MyAttribute *attribute = c.attribute<MyAttribute>( Entity::AddIfMissing );
59 * if ( collection.hasAttribute<MyAttribute>() ) {
60 * *attribute = *collection.attribute<MyAttribute>();
61 * }
62 * // Update the value of 'attribute' ...
63 * Akonadi::CollectionModifyJob *job = new Akonadi::CollectionModifyJob( c );
64 * connect( job, SIGNAL(result(KJob*)), this, SLOT(modifyResult(KJob*)) );
65 *
66 * @endcode
67 *
68 * To update only the collection, and not change any attributes:
69 *
70 * @code
71 *
72 * // Update the cache policy for 'collection' to 'newPolicy'.
73 * Akonadi::Collection c( collection.id() );
74 * c.setCachePolicy( newPolicy );
75 * Akonadi::CollectionModifyJob *job = new Akonadi::CollectionModifyJob( c );
76 * connect( job, SIGNAL(result(KJob*)), this, SLOT(modifyResult(KJob*)) );
77 *
78 * @endcode
79 *
80 * @author Volker Krause <vkrause@kde.org>
81 */
82class AKONADI_EXPORT CollectionModifyJob : public Job
83{
84 Q_OBJECT
85
86public:
87 /**
88 * Creates a new collection modify job for the given collection. The collection can be
89 * identified either by its unique identifier or its remote identifier. Since the remote
90 * identifier is not necessarily globally unique, identification by remote identifier only
91 * works inside a resource context (that is from within ResourceBase) and is therefore
92 * limited to one resource.
93 *
94 * @param collection The collection to modify.
95 * @param parent The parent object.
96 */
97 explicit CollectionModifyJob(const Collection &collection, QObject *parent = 0);
98
99 /**
100 * Destroys the collection modify job.
101 */
102 ~CollectionModifyJob();
103
104 /**
105 * Returns the modified collection.
106 *
107 * @since 4.4
108 */
109 Collection collection() const;
110
111protected:
112 virtual void doStart();
113
114private:
115 Q_DECLARE_PRIVATE(CollectionModifyJob)
116};
117
118}
119
120#endif
121