1/*
2 Copyright (c) 2006 - 2007 Volker Krause <vkrause@kde.org>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef AKONADI_ITEMCREATEJOB_H
21#define AKONADI_ITEMCREATEJOB_H
22
23#include <akonadi/job.h>
24
25namespace Akonadi {
26
27class Collection;
28class Item;
29class ItemCreateJobPrivate;
30
31/**
32 * @short Job that creates a new item in the Akonadi storage.
33 *
34 * This job creates a new item with all the set properties in the
35 * given target collection.
36 *
37 * Note that items can not be created in the root collection (Collection::root())
38 * and the collection must have Collection::contentMimeTypes() that match the mimetype
39 * of the item being created.
40 *
41 * Example:
42 *
43 * @code
44 *
45 * // Create a contact item in the root collection
46 *
47 * KABC::Addressee addr;
48 * addr.setNameFromString( "Joe Jr. Miller" );
49 *
50 * Akonadi::Item item;
51 * item.setMimeType( "text/directory" );
52 * item.setPayload<KABC::Addressee>( addr );
53 *
54 * Akonadi::Collection collection = getCollection();
55 *
56 * Akonadi::ItemCreateJob *job = new Akonadi::ItemCreateJob( item, collection );
57 * connect( job, SIGNAL(result(KJob*)), SLOT(jobFinished(KJob*)) );
58 *
59 * ...
60 *
61 * MyClass::jobFinished( KJob *job )
62 * {
63 * if ( job->error() )
64 * qDebug() << "Error occurred";
65 * else
66 * qDebug() << "Contact item created successfully";
67 * }
68 *
69 * @endcode
70 *
71 * @author Volker Krause <vkrause@kde.org>
72 */
73class AKONADI_EXPORT ItemCreateJob : public Job
74{
75 Q_OBJECT
76
77public:
78 /**
79 * Creates a new item create job.
80 *
81 * @param item The item to create.
82 * @note It must have a mime type set.
83 * @param collection The parent collection where the new item shall be located in.
84 * @param parent The parent object.
85 */
86 ItemCreateJob(const Item &item, const Collection &collection, QObject *parent = 0);
87
88 /**
89 * Destroys the item create job.
90 */
91 ~ItemCreateJob();
92
93 /**
94 * Returns the created item with the new unique id, or an invalid item if the job failed.
95 */
96 Item item() const;
97
98 enum MergeOption {
99 NoMerge = 0, ///< Don't merge
100 RID = 1, ///< Merge by remote id
101 GID = 2, ///< Merge by GID
102 Silent = 4 ///< Only return the id of the merged/created item.
103 };
104 Q_DECLARE_FLAGS(MergeOptions, MergeOption)
105
106 /**
107 * Merge this item into an existing one if available.
108 *
109 * If an item with same GID and/or remote ID as the created item exists in
110 * specified collection (depending on the provided options), the new item will
111 * be merged into the existing one and the merged item will be returned
112 * (unless the Silent option is used).
113 *
114 * If no matching item is found a new item is created.
115 *
116 * If the item does not have a GID or RID, this option will be
117 * ignored and a new item will be created.
118 *
119 * By default, merging is disabled.
120 *
121 * @param options Merge options.
122 * @since 4.14
123 */
124 void setMerge(MergeOptions options);
125
126protected:
127 virtual void doStart();
128 virtual void doHandleResponse(const QByteArray &tag, const QByteArray &data);
129
130private:
131 Q_DECLARE_PRIVATE(ItemCreateJob)
132};
133
134Q_DECLARE_OPERATORS_FOR_FLAGS(ItemCreateJob::MergeOptions)
135
136}
137
138#endif
139