Akonadi::ItemSerializerPlugin Class Reference

#include <itemserializerplugin.h>

Public Member Functions
virtual	~ItemSerializerPlugin ()
virtual QSet< QByteArray >	allowedForeignParts (const Item &item) const
virtual void	apply (Item &item, const Item &other)
virtual QSet< QByteArray >	availableParts (const Item &item) const
virtual bool	deserialize (Item &item, const QByteArray &label, QIODevice &data, int version)=0
virtual QSet< QByteArray >	parts (const Item &item) const
virtual void	serialize (const Item &item, const QByteArray &label, QIODevice &data, int &version)=0

Static Public Member Functions
static void	overridePluginLookup (QObject *plugin)

Detailed Description

The base class for item type serializer plugins.

Serializer plugins convert between the payload of Akonadi::Item objects and a textual or binary representation of the actual content data. This allows to easily add support for new types to Akonadi.

The following example shows how to implement a serializer plugin for a new data type PimNote.

The PimNote data structure:

typedef struct {
  QString author;
  QDateTime dateTime;
  QString text;
} PimNote;

The serializer plugin code:

#include <qplugin.h>
 
class SerializerPluginPimNote : public QObject, public Akonadi::ItemSerializerPlugin
{
  Q_OBJECT
  Q_INTERFACES( Akonadi::ItemSerializerPlugin )
 
  public:
    bool deserialize( Akonadi::Item& item, const QByteArray& label, QIODevice& data, int version )
    {
      // we don't handle versions in this example
      Q_UNUSED(version)
 
      // we work only on full payload
      if ( label != Akonadi::Item::FullPayload )
        return false;
 
      QDataStream stream( &data );
 
      PimNote note;
      stream >> note.author;
      stream >> note.dateTime;
      stream >> note.text;
 
      item.setPayload<PimNote>( note );
 
      return true;
    }
 
    void serialize( const Akonadi::Item& item, const QByteArray& label, QIODevice& data, int &version )
    {
      // we don't handle versions in this example
      Q_UNUSED(version)
 
      if ( label != Akonadi::Item::FullPayload || !item.hasPayload<PimNote>() )
        return;
 
      QDataStream stream( &data );
 
      PimNote note = item.payload<PimNote>();
 
      stream << note.author;
      stream << note.dateTime;
      stream << note.text;
    }
};
 
Q_EXPORT_PLUGIN2( akonadi_serializer_pimnote, SerializerPluginPimNote )

The desktop file:

[Misc]
Name=Pim Note Serializer
Comment=An Akonadi serializer plugin for note objects
 
[Plugin]
Type=application/x-pimnote
X-KDE-Library=akonadi_serializer_pimnote

Author

Till Adam adam@.nosp@m.kde..nosp@m.org, Volker Krause vkrau.nosp@m.se@k.nosp@m.de.or.nosp@m.g

Definition at line 105 of file itemserializerplugin.h.

Constructor & Destructor Documentation

~ItemSerializerPlugin()

ItemSerializerPlugin::~ItemSerializerPlugin ( )

virtualdefault

Destroys the item serializer plugin.

Member Function Documentation

allowedForeignParts()

QSet< QByteArray > ItemSerializerPlugin::allowedForeignParts ( const Item & item ) const

virtual

Returns the parts available in the item item that can be stored using foreign payload mechanism.

Is only called for items whose payload has been set via Item::setPayloadPath().

By default returns "RFC822", which can always be stored as foreign payload. Some implementations can also allow "HEAD" to be stored as foreign payload, if HEAD is only a subset of RFC822 part.

Since

5.7

Definition at line 58 of file itemserializerplugin.cpp.

apply()

void ItemSerializerPlugin::apply ( Item & item, const Item & other )

virtual

Merges the payload parts in other into item.

The default implementation is slow as it requires serializing other, and deserializing item multiple times. Reimplementing this is recommended if your type uses payload parts.

Parameters

item	receives merged parts from other
other	the paylod parts to merge into item

Since

4.4

Definition at line 40 of file itemserializerplugin.cpp.

availableParts()

QSet< QByteArray > ItemSerializerPlugin::availableParts ( const Item & item ) const

virtual

Returns the parts available in the item item.

This should be reimplemented to return available parts.

The default implementation returns an empty set if the item has a payload, and a set containing Item::FullPayload if the item has no payload.

Parameters

item	the item for which to list payload parts

Since

4.4

Definition at line 31 of file itemserializerplugin.cpp.

deserialize()

virtual bool Akonadi::ItemSerializerPlugin::deserialize ( Item & item, const QByteArray & label, QIODevice & data, int version )

pure virtual

Converts serialized item data provided in data into payload for item.

Parameters

item	The item to which the payload should be added. It is guaranteed to have a mime type matching one of the supported mime types of this plugin. However it might contain a unsuited payload added manually by the application developer. Verifying the payload type in case a payload is already available is recommended therefore.
label	The part identifier of the part to deserialize. label might be an unsupported item part, return false if this is the case.
data	A QIODevice providing access to the serialized data. The QIODevice is opened in read-only mode and positioned at the beginning. The QIODevice is guaranteed to be valid.
version	The version of the data format as set by the user in serialize() or 0 (default).

Returns

false if the specified part is not supported by this plugin, true if the part could be de-serialized successfully.

overridePluginLookup()

void ItemSerializerPlugin::overridePluginLookup ( QObject * plugin )

static

Override the plugin-lookup with plugin.

After calling this each lookup will always return plugin. This is useful to inject a special plugin for testing purposes. To reset the plugin, set to 0.

Since

4.12

Definition at line 26 of file itemserializerplugin.cpp.

parts()

QSet< QByteArray > ItemSerializerPlugin::parts ( const Item & item ) const

virtual

Returns a list of available parts for the given item payload.

The default implementation returns Item::FullPayload if a payload is set.

Parameters

item

The item.

Definition at line 17 of file itemserializerplugin.cpp.

serialize()

virtual void Akonadi::ItemSerializerPlugin::serialize ( const Item & item, const QByteArray & label, QIODevice & data, int & version )

pure virtual

Convert the payload object provided in item into its serialzed form into data.

Parameters

item	The item which contains the payload. It is guaranteed to have a mimetype matching one of the supported mimetypes of this plugin as well as the existence of a payload object. However it might contain an unsupported payload added manually by the application developer. Verifying the payload type is recommended therefore.
label	The part identifier of the part to serialize. label will be one of the item parts returned by parts().
data	The QIODevice where the serialized data should be written to. The QIODevice is opened in write-only mode and positioned at the beginning. The QIODevice is guaranteed to be valid.
version	The version of the data format. Can be set by the user to handle different versions.

---

The documentation for this class was generated from the following files:

• itemserializerplugin.h
• itemserializerplugin.cpp