Akonadi

itemserializerplugin.h
1/*
2 SPDX-FileCopyrightText: 2007 Till Adam <adam@kde.org>
3 SPDX-FileCopyrightText: 2007 Volker Krause <vkrause@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#pragma once
9
10#include <QByteArray>
11#include <QSet>
12
13#include "akonadicore_export.h"
14#include "item.h"
15
16class QIODevice;
17
18namespace Akonadi
19{
20/**
21 * @short The base class for item type serializer plugins.
22 *
23 * Serializer plugins convert between the payload of Akonadi::Item objects and
24 * a textual or binary representation of the actual content data.
25 * This allows to easily add support for new types to Akonadi.
26 *
27 * The following example shows how to implement a serializer plugin for
28 * a new data type PimNote.
29 *
30 * The PimNote data structure:
31 * @code
32 * typedef struct {
33 * QString author;
34 * QDateTime dateTime;
35 * QString text;
36 * } PimNote;
37 * @endcode
38 *
39 * The serializer plugin code:
40 * @code
41 * #include <qplugin.h>
42 *
43 * class SerializerPluginPimNote : public QObject, public Akonadi::ItemSerializerPlugin
44 * {
45 * Q_OBJECT
46 * Q_INTERFACES( Akonadi::ItemSerializerPlugin )
47 *
48 * public:
49 * bool deserialize( Akonadi::Item& item, const QByteArray& label, QIODevice& data, int version )
50 * {
51 * // we don't handle versions in this example
52 * Q_UNUSED(version)
53 *
54 * // we work only on full payload
55 * if ( label != Akonadi::Item::FullPayload )
56 * return false;
57 *
58 * QDataStream stream( &data );
59 *
60 * PimNote note;
61 * stream >> note.author;
62 * stream >> note.dateTime;
63 * stream >> note.text;
64 *
65 * item.setPayload<PimNote>( note );
66 *
67 * return true;
68 * }
69 *
70 * void serialize( const Akonadi::Item& item, const QByteArray& label, QIODevice& data, int &version )
71 * {
72 * // we don't handle versions in this example
73 * Q_UNUSED(version)
74 *
75 * if ( label != Akonadi::Item::FullPayload || !item.hasPayload<PimNote>() )
76 * return;
77 *
78 * QDataStream stream( &data );
79 *
80 * PimNote note = item.payload<PimNote>();
81 *
82 * stream << note.author;
83 * stream << note.dateTime;
84 * stream << note.text;
85 * }
86 * };
87 *
88 * Q_EXPORT_PLUGIN2( akonadi_serializer_pimnote, SerializerPluginPimNote )
89 *
90 * @endcode
91 *
92 * The desktop file:
93 * @code
94 * [Misc]
95 * Name=Pim Note Serializer
96 * Comment=An Akonadi serializer plugin for note objects
97 *
98 * [Plugin]
99 * Type=application/x-pimnote
100 * X-KDE-Library=akonadi_serializer_pimnote
101 * @endcode
102 *
103 * @author Till Adam <adam@kde.org>, Volker Krause <vkrause@kde.org>
104 */
105class AKONADICORE_EXPORT ItemSerializerPlugin
106{
107public:
108 /**
109 * Destroys the item serializer plugin.
110 */
112
113 /**
114 * Converts serialized item data provided in @p data into payload for @p item.
115 *
116 * @param item The item to which the payload should be added.
117 * It is guaranteed to have a mime type matching one of the supported
118 * mime types of this plugin.
119 * However it might contain a unsuited payload added manually
120 * by the application developer.
121 * Verifying the payload type in case a payload is already available
122 * is recommended therefore.
123 * @param label The part identifier of the part to deserialize.
124 * @p label might be an unsupported item part, return @c false if this is the case.
125 * @param data A QIODevice providing access to the serialized data.
126 * The QIODevice is opened in read-only mode and positioned at the beginning.
127 * The QIODevice is guaranteed to be valid.
128 * @param version The version of the data format as set by the user in serialize() or @c 0 (default).
129 * @return @c false if the specified part is not supported by this plugin, @c true if the part
130 * could be de-serialized successfully.
131 */
132 virtual bool deserialize(Item &item, const QByteArray &label, QIODevice &data, int version) = 0;
133
134 /**
135 * Convert the payload object provided in @p item into its serialzed form into @p data.
136 *
137 * @param item The item which contains the payload.
138 * It is guaranteed to have a mimetype matching one of the supported
139 * mimetypes of this plugin as well as the existence of a payload object.
140 * However it might contain an unsupported payload added manually by
141 * the application developer.
142 * Verifying the payload type is recommended therefore.
143 * @param label The part identifier of the part to serialize.
144 * @p label will be one of the item parts returned by parts().
145 * @param data The QIODevice where the serialized data should be written to.
146 * The QIODevice is opened in write-only mode and positioned at the beginning.
147 * The QIODevice is guaranteed to be valid.
148 * @param version The version of the data format. Can be set by the user to handle different
149 * versions.
150 */
151 virtual void serialize(const Item &item, const QByteArray &label, QIODevice &data, int &version) = 0;
152
153 /**
154 * Returns a list of available parts for the given item payload.
155 * The default implementation returns Item::FullPayload if a payload is set.
156 *
157 * @param item The item.
158 */
159 virtual QSet<QByteArray> parts(const Item &item) const;
160
161 /**
162 * Override the plugin-lookup with @p plugin.
163 *
164 * After calling this each lookup will always return @p plugin.
165 * This is useful to inject a special plugin for testing purposes.
166 * To reset the plugin, set to 0.
167 *
168 * @since 4.12
169 */
170 static void overridePluginLookup(QObject *plugin);
171
172 /**
173 * Merges the payload parts in @p other into @p item.
174 *
175 * The default implementation is slow as it requires serializing @p other, and deserializing @p item multiple times.
176 * Reimplementing this is recommended if your type uses payload parts.
177 * @param item receives merged parts from @p other
178 * @param other the paylod parts to merge into @p item
179 * @since 4.4
180 */
181 virtual void apply(Item &item, const Item &other);
182
183 /**
184 * Returns the parts available in the item @p item.
185 *
186 * This should be reimplemented to return available parts.
187 *
188 * The default implementation returns an empty set if the item has a payload,
189 * and a set containing Item::FullPayload if the item has no payload.
190 * @param item the item for which to list payload parts
191 * @since 4.4
192 */
193 virtual QSet<QByteArray> availableParts(const Item &item) const;
194
195 /**
196 * Returns the parts available in the item @p item that can be stored using
197 * foreign payload mechanism. Is only called for items whose payload has been
198 * set via Item::setPayloadPath().
199 *
200 * By default returns "RFC822", which can always be stored as foreign payload.
201 * Some implementations can also allow "HEAD" to be stored as foreign payload,
202 * if HEAD is only a subset of RFC822 part.
203 *
204 * @since 5.7
205 */
206 virtual QSet<QByteArray> allowedForeignParts(const Item &item) const;
207
208protected:
209 explicit ItemSerializerPlugin() = default;
210
211private:
212 Q_DISABLE_COPY_MOVE(ItemSerializerPlugin)
213};
214
215}
216
217Q_DECLARE_INTERFACE(Akonadi::ItemSerializerPlugin, "org.freedesktop.Akonadi.ItemSerializerPlugin/2.0")
The base class for item type serializer plugins.
virtual bool deserialize(Item &item, const QByteArray &label, QIODevice &data, int version)=0
Converts serialized item data provided in data into payload for item.
virtual void serialize(const Item &item, const QByteArray &label, QIODevice &data, int &version)=0
Convert the payload object provided in item into its serialzed form into data.
virtual ~ItemSerializerPlugin()
Destroys the item serializer plugin.
Represents a PIM item stored in Akonadi storage.
Definition item.h:100
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:00:59 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.