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
30class QIODevice;
31
32namespace 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 */
119class AKONADI_EXPORT ItemSerializerPlugin
120{
121public:
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 */
193class AKONADI_EXPORT ItemSerializerPluginV2 : public ItemSerializerPlugin
194{
195public:
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
227Q_DECLARE_INTERFACE(Akonadi::ItemSerializerPlugin, "org.freedesktop.Akonadi.ItemSerializerPlugin/1.0")
228Q_DECLARE_INTERFACE(Akonadi::ItemSerializerPluginV2, "org.freedesktop.Akonadi.ItemSerializerPlugin/1.1")
229
230#endif
231