Akonadi

collectionmodifyjob.h
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
12namespace Akonadi
13{
14class CachePolicy;
15class Collection;
16class 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 */
67class AKONADICORE_EXPORT CollectionModifyJob : public Job
68{
69 Q_OBJECT
70
71public:
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 [[nodiscard]] Collection collection() const;
95
96protected:
97 void doStart() override;
98 bool doHandleResponse(qint64 tag, const Protocol::CommandPtr &response) override;
99
100private:
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:62
Base class for all actions in the Akonadi storage.
Definition job.h:81
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 21 2024 11:57:48 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.