Akonadi

itemcreatejob.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 "job.h"
11 
12 namespace Akonadi
13 {
14 class Collection;
15 class Item;
16 class 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 <[email protected]>
59  */
60 class AKONADICORE_EXPORT ItemCreateJob : public Job
61 {
62  Q_OBJECT
63 
64 public:
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  Q_REQUIRED_RESULT Item item() const;
84 
85  enum MergeOption {
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 
113 protected:
114  void doStart() override;
115  bool doHandleResponse(qint64 tag, const Protocol::CommandPtr &response) override;
116 
117 private:
118  Q_DECLARE_PRIVATE(ItemCreateJob)
119 };
120 
121 Q_DECLARE_OPERATORS_FOR_FLAGS(ItemCreateJob::MergeOptions)
122 
123 }
124 
Job that creates a new item in the Akonadi storage.
Definition: itemcreatejob.h:60
Represents a collection of PIM items.
Definition: collection.h:61
Base class for all actions in the Akonadi storage.
Definition: job.h:80
Represents a PIM item stored in Akonadi storage.
Definition: item.h:104
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jul 2 2022 06:41:48 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.