Akonadi

itemmodifyjob.h
1/*
2 SPDX-FileCopyrightText: 2006-2007 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 "item.h"
11#include "job.h"
12
13namespace Akonadi
14{
15class 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 <vkrause@kde.org>
80 */
81class AKONADICORE_EXPORT ItemModifyJob : public Job
82{
83 friend class ResourceBase;
84
85 Q_OBJECT
86
87public:
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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] Item item() const;
165
166 /**
167 * Returns the modified and stored items including the changed revision number.
168 *
169 * @since 4.6
170 */
171 [[nodiscard]] 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
185protected:
186 void doStart() override;
187 bool doHandleResponse(qint64 tag, const Protocol::CommandPtr &response) override;
188
189private:
190 /// @cond PRIVATE
191 Q_DECLARE_PRIVATE(ItemModifyJob)
192 /// @endcond
193};
194
195}
Job that modifies an existing item in the Akonadi storage.
Represents a PIM item stored in Akonadi storage.
Definition item.h:100
Base class for all actions in the Akonadi storage.
Definition job.h:81
The base class for all Akonadi resources.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:00:59 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.