Akonadi

itemmodifyjob.h
1 /*
2  SPDX-FileCopyrightText: 2006-2007 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 "item.h"
11 #include "job.h"
12 
13 namespace Akonadi
14 {
15 class ItemModifyJobPrivate;
16 
17 /**
18  * @short Job that modifies an existing item in the Akonadi storage.
19  *
20  * This job is used to writing back items to the Akonadi storage, after
21  * the user has changed them in any way.
22  * For performance reasons either the full item (including the full payload)
23  * can written back or only the meta data of the item.
24  *
25  * Example:
26  *
27  * @code
28  *
29  * // Fetch item with unique id 125
30  * Akonadi::ItemFetchJob *fetchJob = new Akonadi::ItemFetchJob( Akonadi::Item( 125 ) );
31  * connect( fetchJob, SIGNAL(result(KJob*)), SLOT(fetchFinished(KJob*)) );
32  *
33  * ...
34  *
35  * MyClass::fetchFinished( KJob *job )
36  * {
37  * if ( job->error() )
38  * return;
39  *
40  * Akonadi::ItemFetchJob *fetchJob = qobject_cast<Akonadi::ItemFetchJob*>( job );
41  *
42  * Akonadi::Item item = fetchJob->items().at(0);
43  *
44  * // Set a custom flag
45  * item.setFlag( "\GotIt" );
46  *
47  * // Store back modified item
48  * Akonadi::ItemModifyJob *modifyJob = new Akonadi::ItemModifyJob( item );
49  * connect( modifyJob, SIGNAL(result(KJob*)), SLOT(modifyFinished(KJob*)) );
50  * }
51  *
52  * MyClass::modifyFinished( KJob *job )
53  * {
54  * if ( job->error() )
55  * qDebug() << "Error occurred";
56  * else
57  * qDebug() << "Item modified successfully";
58  * }
59  *
60  * @endcode
61  *
62  * <h3>Conflict Resolution</h3>
63 
64  * When the job is executed, a check is made to ensure that the Item contained
65  * in the job is not older than the version of the Item already held in the
66  * Akonadi database. If it is older, a conflict resolution dialog is displayed
67  * for the user to choose which version of the Item to use, unless
68  * disableAutomaticConflictHandling() has been called to disable the dialog, or
69  * disableRevisionCheck() has been called to disable version checking
70  * altogether.
71  *
72  * The item version is checked by comparing the Item::revision() values in the
73  * job and in the database. To ensure that two successive ItemModifyJobs for
74  * the same Item work correctly, the revision number of the Item supplied to
75  * the second ItemModifyJob should be set equal to the Item's revision number
76  * on completion of the first ItemModifyJob. This can be obtained by, for
77  * example, calling item().revision() in the job's result slot.
78  *
79  * @author Volker Krause <[email protected]>
80  */
81 class AKONADICORE_EXPORT ItemModifyJob : public Job
82 {
83  friend class ResourceBase;
84 
85  Q_OBJECT
86 
87 public:
88  /**
89  * Creates a new item modify job.
90  *
91  * @param item The modified item object to store.
92  * @param parent The parent object.
93  */
94  explicit ItemModifyJob(const Item &item, QObject *parent = nullptr);
95 
96  /**
97  * Creates a new item modify job for bulk modifications.
98  *
99  * Using this is different from running a modification job per item.
100  * Use this when applying the same change to a set of items, such as a
101  * mass-change of item flags, not if you just want to store a bunch of
102  * randomly modified items.
103  *
104  * Currently the following modifications are supported:
105  * - flag changes
106  *
107  * @note Since this does not do payload modifications, it implies
108  * setIgnorePayload( true ) and disableRevisionCheck().
109  * @param items The list of items to modify, must not be empty.
110  * @since 4.6
111  */
112  explicit ItemModifyJob(const Item::List &items, QObject *parent = nullptr);
113 
114  /**
115  * Destroys the item modify job.
116  */
117  ~ItemModifyJob() override;
118 
119  /**
120  * Sets whether the payload of the modified item shall be
121  * omitted from transmission to the Akonadi storage.
122  * The default is @c false, however it can be set for
123  * performance reasons.
124  * @param ignore ignores payload if set as @c true
125  */
126  void setIgnorePayload(bool ignore);
127 
128  /**
129  * Returns whether the payload of the modified item shall be
130  * omitted from transmission to the Akonadi storage.
131  */
132  Q_REQUIRED_RESULT bool ignorePayload() const;
133 
134  /**
135  * Sets whether the GID shall be updated either from the gid parameter or
136  * by extracting it from the payload.
137  * The default is @c false to avoid unnecessarily update the GID,
138  * as it should never change once set, and the ItemCreateJob already sets it.
139  * @param update update the GID if set as @c true
140  *
141  * @note If disabled the GID will not be updated, but still be used for identification of the item.
142  * @since 4.12
143  */
144  void setUpdateGid(bool update);
145 
146  /**
147  * Returns whether the GID should be updated.
148  * @since 4.12
149  */
150  Q_REQUIRED_RESULT bool updateGid() const;
151 
152  /**
153  * Disables the check of the revision number.
154  *
155  * @note If disabled, no conflict detection is available.
156  */
157  void disableRevisionCheck();
158 
159  /**
160  * Returns the modified and stored item including the changed revision number.
161  *
162  * @note Use this method only when using the single item constructor.
163  */
164  Q_REQUIRED_RESULT Item item() const;
165 
166  /**
167  * Returns the modified and stored items including the changed revision number.
168  *
169  * @since 4.6
170  */
171  Q_REQUIRED_RESULT Item::List items() const;
172 
173  /**
174  * Disables the automatic handling of conflicts.
175  *
176  * By default the item modify job will bring up a dialog to resolve
177  * a conflict that might happen when modifying an item.
178  * Calling this method will avoid that and the job returns with an
179  * error in case of a conflict.
180  *
181  * @since 4.6
182  */
183  void disableAutomaticConflictHandling();
184 
185 protected:
186  void doStart() override;
187  bool doHandleResponse(qint64 tag, const Protocol::CommandPtr &response) override;
188 
189 private:
190  /// @cond PRIVATE
191  Q_DECLARE_PRIVATE(ItemModifyJob)
192  /// @endcond
193 };
194 
195 }
Job that modifies an existing item in the Akonadi storage.
Definition: itemmodifyjob.h:81
Base class for all actions in the Akonadi storage.
Definition: job.h:80
The base class for all Akonadi resources.
Definition: resourcebase.h:134
Represents a PIM item stored in Akonadi storage.
Definition: item.h:100
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Sep 29 2023 03:51:14 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.