1 | /* |
2 | Copyright (c) 2007 Till Adam <adam@kde.org> |
3 | Copyright (c) 2007 Volker Krause <vkrause@kde.org> |
4 | |
5 | This library is free software; you can redistribute it and/or modify it |
6 | under the terms of the GNU Library General Public License as published by |
7 | the Free Software Foundation; either version 2 of the License, or (at your |
8 | option) any later version. |
9 | |
10 | This library is distributed in the hope that it will be useful, but WITHOUT |
11 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
12 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public |
13 | License for more details. |
14 | |
15 | You should have received a copy of the GNU Library General Public License |
16 | along with this library; see the file COPYING.LIB. If not, write to the |
17 | Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA |
18 | 02110-1301, USA. |
19 | */ |
20 | |
21 | #ifndef AKONADI_ITEMSERIALIZERPLUGIN_H |
22 | #define AKONADI_ITEMSERIALIZERPLUGIN_H |
23 | |
24 | #include <QtCore/QByteArray> |
25 | #include <QtCore/QSet> |
26 | |
27 | #include "item.h" |
28 | #include "akonadi_export.h" |
29 | |
30 | class QIODevice; |
31 | |
32 | namespace Akonadi { |
33 | |
34 | /** |
35 | * @short The base class for item type serializer plugins. |
36 | * |
37 | * Serializer plugins convert between the payload of Akonadi::Item objects and |
38 | * a textual or binary representation of the actual content data. |
39 | * This allows to easily add support for new types to Akonadi. |
40 | * |
41 | * The following example shows how to implement a serializer plugin for |
42 | * a new data type PimNote. |
43 | * |
44 | * The PimNote data structure: |
45 | * @code |
46 | * typedef struct { |
47 | * QString author; |
48 | * QDateTime dateTime; |
49 | * QString text; |
50 | * } PimNote; |
51 | * @endcode |
52 | * |
53 | * The serializer plugin code: |
54 | * @code |
55 | * #include <QtCore/qplugin.h> |
56 | * |
57 | * class SerializerPluginPimNote : public QObject, public Akonadi::ItemSerializerPlugin |
58 | * { |
59 | * Q_OBJECT |
60 | * Q_INTERFACES( Akonadi::ItemSerializerPlugin ) |
61 | * |
62 | * public: |
63 | * bool deserialize( Akonadi::Item& item, const QByteArray& label, QIODevice& data, int version ) |
64 | * { |
65 | * // we don't handle versions in this example |
66 | * Q_UNUSED( version ); |
67 | * |
68 | * // we work only on full payload |
69 | * if ( label != Akonadi::Item::FullPayload ) |
70 | * return false; |
71 | * |
72 | * QDataStream stream( &data ); |
73 | * |
74 | * PimNote note; |
75 | * stream >> note.author; |
76 | * stream >> note.dateTime; |
77 | * stream >> note.text; |
78 | * |
79 | * item.setPayload<PimNote>( note ); |
80 | * |
81 | * return true; |
82 | * } |
83 | * |
84 | * void serialize( const Akonadi::Item& item, const QByteArray& label, QIODevice& data, int &version ) |
85 | * { |
86 | * // we don't handle versions in this example |
87 | * Q_UNUSED( version ); |
88 | * |
89 | * if ( label != Akonadi::Item::FullPayload || !item.hasPayload<PimNote>() ) |
90 | * return; |
91 | * |
92 | * QDataStream stream( &data ); |
93 | * |
94 | * PimNote note = item.payload<PimNote>(); |
95 | * |
96 | * stream << note.author; |
97 | * stream << note.dateTime; |
98 | * stream << note.text; |
99 | * } |
100 | * }; |
101 | * |
102 | * Q_EXPORT_PLUGIN2( akonadi_serializer_pimnote, SerializerPluginPimNote ) |
103 | * |
104 | * @endcode |
105 | * |
106 | * The desktop file: |
107 | * @code |
108 | * [Misc] |
109 | * Name=Pim Note Serializer |
110 | * Comment=An Akonadi serializer plugin for note objects |
111 | * |
112 | * [Plugin] |
113 | * Type=application/x-pimnote |
114 | * X-KDE-Library=akonadi_serializer_pimnote |
115 | * @endcode |
116 | * |
117 | * @author Till Adam <adam@kde.org>, Volker Krause <vkrause@kde.org> |
118 | */ |
119 | class AKONADI_EXPORT ItemSerializerPlugin |
120 | { |
121 | public: |
122 | /** |
123 | * Destroys the item serializer plugin. |
124 | */ |
125 | virtual ~ItemSerializerPlugin(); |
126 | |
127 | /** |
128 | * Converts serialized item data provided in @p data into payload for @p item. |
129 | * |
130 | * @param item The item to which the payload should be added. |
131 | * It is guaranteed to have a mime type matching one of the supported |
132 | * mime types of this plugin. |
133 | * However it might contain a unsuited payload added manually |
134 | * by the application developer. |
135 | * Verifying the payload type in case a payload is already available |
136 | * is recommended therefore. |
137 | * @param label The part identifier of the part to deserialize. |
138 | * @p label might be an unsupported item part, return @c false if this is the case. |
139 | * @param data A QIODevice providing access to the serialized data. |
140 | * The QIODevice is opened in read-only mode and positioned at the beginning. |
141 | * The QIODevice is guaranteed to be valid. |
142 | * @param version The version of the data format as set by the user in serialize() or @c 0 (default). |
143 | * @return @c false if the specified part is not supported by this plugin, @c true if the part |
144 | * could be de-serialized successfully. |
145 | */ |
146 | virtual bool deserialize(Item &item, const QByteArray &label, QIODevice &data, int version) = 0; |
147 | |
148 | /** |
149 | * Convert the payload object provided in @p item into its serialzed form into @p data. |
150 | * |
151 | * @param item The item which contains the payload. |
152 | * It is guaranteed to have a mimetype matching one of the supported |
153 | * mimetypes of this plugin as well as the existence of a payload object. |
154 | * However it might contain an unsupported payload added manually by |
155 | * the application developer. |
156 | * Verifying the payload type is recommended therefore. |
157 | * @param label The part identifier of the part to serialize. |
158 | * @p label will be one of the item parts returned by parts(). |
159 | * @param data The QIODevice where the serialized data should be written to. |
160 | * The QIODevice is opened in write-only mode and positioned at the beginning. |
161 | * The QIODevice is guaranteed to be valid. |
162 | * @param version The version of the data format. Can be set by the user to handle different |
163 | * versions. |
164 | */ |
165 | virtual void serialize(const Item &item, const QByteArray &label, QIODevice &data, int &version) = 0; |
166 | |
167 | /** |
168 | * Returns a list of available parts for the given item payload. |
169 | * The default implementation returns Item::FullPayload if a payload is set. |
170 | * |
171 | * @param item The item. |
172 | */ |
173 | virtual QSet<QByteArray> parts(const Item &item) const; |
174 | |
175 | /** |
176 | * Override the plugin-lookup with @p plugin. |
177 | * |
178 | * After calling this each lookup will always return @p plugin. |
179 | * This is useful to inject a special plugin for testing purposes. |
180 | * To reset the plugin, set to 0. |
181 | * |
182 | * @since 4.12 |
183 | */ |
184 | static void overridePluginLookup(QObject *plugin); |
185 | |
186 | }; |
187 | |
188 | /** |
189 | * @short The extended base class for item type serializer plugins. |
190 | * |
191 | * @since 4.4 |
192 | */ |
193 | class AKONADI_EXPORT ItemSerializerPluginV2 : public ItemSerializerPlugin |
194 | { |
195 | public: |
196 | /** |
197 | * Destroys the item serializer plugin. |
198 | */ |
199 | virtual ~ItemSerializerPluginV2(); |
200 | |
201 | /** |
202 | * Merges the payload parts in @p other into @p item. |
203 | * |
204 | * The default implementation is slow as it requires serializing @p other, and deserializing @p item multiple times. |
205 | * Reimplementing this is recommended if your type uses payload parts. |
206 | * @param item receives merged parts from @p other |
207 | * @param other the paylod parts to merge into @p item |
208 | * @since 4.4 |
209 | */ |
210 | virtual void apply(Item &item, const Item &other); |
211 | |
212 | /** |
213 | * Returns the parts available in the item @p item. |
214 | * |
215 | * This should be reimplemented to return available parts. |
216 | * |
217 | * The default implementation returns an empty set if the item has a payload, |
218 | * and a set containing Item::FullPayload if the item has no payload. |
219 | * @param item the item for which to list payload parts |
220 | * @since 4.4 |
221 | */ |
222 | virtual QSet<QByteArray> availableParts(const Item &item) const; |
223 | }; |
224 | |
225 | } |
226 | |
227 | Q_DECLARE_INTERFACE(Akonadi::ItemSerializerPlugin, "org.freedesktop.Akonadi.ItemSerializerPlugin/1.0" ) |
228 | Q_DECLARE_INTERFACE(Akonadi::ItemSerializerPluginV2, "org.freedesktop.Akonadi.ItemSerializerPlugin/1.1" ) |
229 | |
230 | #endif |
231 | |