Akonadi

itemcreatejob.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 "job.h"
11
12namespace Akonadi
13{
14class Collection;
15class Item;
16class ItemCreateJobPrivate;
17
18/**
19 * @short Job that creates a new item in the Akonadi storage.
20 *
21 * This job creates a new item with all the set properties in the
22 * given target collection.
23 *
24 * Note that items can not be created in the root collection (Collection::root())
25 * and the collection must have Collection::contentMimeTypes() that match the mimetype
26 * of the item being created.
27 *
28 * Example:
29 *
30 * @code
31 *
32 * // Create a contact item in the root collection
33 *
34 * KContacts::Addressee addr;
35 * addr.setNameFromString( "Joe Jr. Miller" );
36 *
37 * Akonadi::Item item;
38 * item.setMimeType( "text/directory" );
39 * item.setPayload<KContacts::Addressee>( addr );
40 *
41 * Akonadi::Collection collection = getCollection();
42 *
43 * Akonadi::ItemCreateJob *job = new Akonadi::ItemCreateJob( item, collection );
44 * connect( job, SIGNAL(result(KJob*)), SLOT(jobFinished(KJob*)) );
45 *
46 * ...
47 *
48 * MyClass::jobFinished( KJob *job )
49 * {
50 * if ( job->error() )
51 * qDebug() << "Error occurred";
52 * else
53 * qDebug() << "Contact item created successfully";
54 * }
55 *
56 * @endcode
57 *
58 * @author Volker Krause <vkrause@kde.org>
59 */
60class AKONADICORE_EXPORT ItemCreateJob : public Job
61{
62 Q_OBJECT
63
64public:
65 /**
66 * Creates a new item create job.
67 *
68 * @param item The item to create.
69 * @note It must have a mime type set.
70 * @param collection The parent collection where the new item shall be located in.
71 * @param parent The parent object.
72 */
73 ItemCreateJob(const Item &item, const Collection &collection, QObject *parent = nullptr);
74
75 /**
76 * Destroys the item create job.
77 */
78 ~ItemCreateJob() override;
79
80 /**
81 * Returns the created item with the new unique id, or an invalid item if the job failed.
82 */
83 [[nodiscard]] Item item() const;
84
86 NoMerge = 0, ///< Don't merge
87 RID = 1, ///< Merge by remote id
88 GID = 2, ///< Merge by GID
89 Silent = 4 ///< Only return the id of the merged/created item.
90 };
91 Q_DECLARE_FLAGS(MergeOptions, MergeOption)
92
93 /**
94 * Merge this item into an existing one if available.
95 *
96 * If an item with same GID and/or remote ID as the created item exists in
97 * specified collection (depending on the provided options), the new item will
98 * be merged into the existing one and the merged item will be returned
99 * (unless the Silent option is used).
100 *
101 * If no matching item is found a new item is created.
102 *
103 * If the item does not have a GID or RID, this option will be
104 * ignored and a new item will be created.
105 *
106 * By default, merging is disabled.
107 *
108 * @param options Merge options.
109 * @since 4.14
110 */
111 void setMerge(MergeOptions options);
112
113protected:
114 void doStart() override;
115 bool doHandleResponse(qint64 tag, const Protocol::CommandPtr &response) override;
116
117private:
118 Q_DECLARE_PRIVATE(ItemCreateJob)
119};
120
121Q_DECLARE_OPERATORS_FOR_FLAGS(ItemCreateJob::MergeOptions)
122
123}
Represents a collection of PIM items.
Definition collection.h:62
Job that creates a new 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
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:01:42 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.