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 | |
25 | namespace Akonadi { |
26 | |
27 | class Collection; |
28 | class Item; |
29 | class 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 | */ |
73 | class AKONADI_EXPORT ItemCreateJob : public Job |
74 | { |
75 | Q_OBJECT |
76 | |
77 | public: |
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 | |
126 | protected: |
127 | virtual void doStart(); |
128 | virtual void doHandleResponse(const QByteArray &tag, const QByteArray &data); |
129 | |
130 | private: |
131 | Q_DECLARE_PRIVATE(ItemCreateJob) |
132 | }; |
133 | |
134 | Q_DECLARE_OPERATORS_FOR_FLAGS(ItemCreateJob::MergeOptions) |
135 | |
136 | } |
137 | |
138 | #endif |
139 | |