Akonadi

itemserializerplugin.h
1 /*
2  SPDX-FileCopyrightText: 2007 Till Adam <[email protected]>
3  SPDX-FileCopyrightText: 2007 Volker Krause <[email protected]>
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 
16 class QIODevice;
17 
18 namespace 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 <[email protected]>, Volker Krause <[email protected]>
104  */
105 class AKONADICORE_EXPORT ItemSerializerPlugin
106 {
107 public:
108  /**
109  * Destroys the item serializer plugin.
110  */
111  virtual ~ItemSerializerPlugin();
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 
208 protected:
209  explicit ItemSerializerPlugin() = default;
210 
211 private:
212  Q_DISABLE_COPY_MOVE(ItemSerializerPlugin)
213 };
214 
215 }
216 
217 Q_DECLARE_INTERFACE(Akonadi::ItemSerializerPlugin, "org.freedesktop.Akonadi.ItemSerializerPlugin/2.0")
The base class for item type serializer plugins.
Represents a PIM item stored in Akonadi storage.
Definition: item.h:105
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Jun 7 2023 03:53:31 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.