Development/Tutorials/Akonadi/Resources

This tutorial will guide you through the steps of creating an Akonadi resource, an agent program which transports PIM data between the Akonadi system and a storage backend.

The resource developed in this tutorial will use a directory on the local file system as its backend and handle contact data, i.e. address book entries.

Prerequisites

TODO

Preparation

We can kick-start the resource by using KAppTemplate, which can be found as KDE template generator in the development section of the K-menu.

First, we select the Akonadi Resource Template in the C++ section of the program, give our project a name and continue through the following pages to complete the template creation.

TODO: embed screenshots

A look at the generated project directory shows us the following files: akonadi-resources.png Messages.sh settings.kcfgc vcarddirresource.desktop vcarddirresource.kcfg CMakeLists.txt README vcarddirresource.cpp vcarddirresource.h

At this stage it is already possible to compile the resource, so we can already check if our development environment is setup correctly by creating the build directory and having CMake either generate Makefiles or a KDevelop project file.

Generating Makefiles

mkdir build cd build cmake -DCMAKE_BUILD_TYPE=debugfull .. and run the build using make as usual.

Generating a KDevelop project file

mkdir build cd build cmake -DCMAKE_BUILD_TYPE=debugfull -G KDevelop3 .. and open the generated project with KDevelop and run the build process from there.

Adjusting the resource description file

The capabilities of the resource need to be described in both human understable and machine interpretable form. This is achieved through a so-called desktop file, similar to those installed by applications.

Since the vcarddirresource.desktop file generated by KAppTemplate contains only example values, we need to edit it:

[Desktop Entry] Name=Akonadi VCardDir Resource Comment=Resource for a directory containing contact data files

Type=AkonadiResource Exec=akonadi_vcarddir_resource Icon=text-directory

X-Akonadi-MimeTypes=text/directory X-Akonadi-Capabilities=Resource X-Akonadi-Identifier=akonadi_vcarddir_resource

Name and Comment are strings visible to the user and can be translated. Since our resource will serve contact data, the example valued for Icon and X-Akonadi-MimeTypes fields are conveniently correct.

Resource Configuration

Since the backend of our resource will be a file system directory, we need a way to let the user configure it and a way to persistantly store this configuration.

KDE has a nice framework for this called KConfig XT which enabled us developers to specify our config options as an XML file and have the code for storage and retrieval auto-generated.

The template we are basing our resource on already contains such a file, vcarddirresource.kcfg, and we only have to add our new option: <?xml version="1.0" encoding="UTF-8"?> <kcfg xmlns="http://www.kde.org/standards/kcfg/1.0"

     xmlns:kcfg="http://www.kde.org/standards/kcfg/1.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.kde.org/standards/kcfg/1.0
     http://www.kde.org/standards/kcfg/1.0/kcfg.xsd" >
 <group name="General">
   <entry name="Path" type="Path">
     <label>Path to a folder containing vCard files.</label>
     <default></default>
   </entry>
   <entry name="ReadOnly" type="Bool">
     <label>Do not change the actual backend data.</label>
     <default>false</default>
   </entry>
 </group>

</kcfg>

To enable the user to change this properties, we need to create and show a config dialog. Since we are using KConfig XT this is pretty easy, but for the scope of this tutorial we make our lives even more easier and just use a KFileDialog

First we need to add two new include directives at the beginning of our source file vcarddirresource.cpp:

1. include <kfiledialog.h>
2. include <klocalizedstring.h>

To show the dialog on the user's request, we need to modify the resource method configure which currently has an empty implementations. void VCardDirResource::configure( WId windowId ) {

 Q_UNUSED( windowId );

 const QString oldPath = Settings::self()->path();
 KUrl url;
 if ( !oldPath.isEmpty() )
   url = KUrl::fromPath( oldPath );
 else
   url = KUrl::fromPath( QDir::homePath() );

 const QString title = i18nc( "@title:window", "Select vCard folder" );
 const QString newPath = KFileDialog::getExistingDirectory( url, 0, title );

 if ( newPath.isEmpty() )
   return;

 if ( oldPath == newPath )
   return;

 Settings::self()->setPath( newPath );

 Settings::self()->writeConfig();

 synchronize();

}

The call to synchronize at the end tells Akonadi to start retrieving the new data from our resource.

Data Retrieval

In this section of the tutorial we will implement the data retrieval methods of our resource, i.e. the method which Akonadi will call to get the contact data our resource is providing.

Retrieving Collections

The first thing Akonadi will ask for are our collections. Resources can organize their data in a tree of collections, similar to how files are organized in a tree of directories on the file system.

For now we only want to support one directory so we only need one collection. Exercise: Extend this to map a tree of vCard directories into Akonadi.

Retrieval of collections is handled in retrieveCollections: void VCardDirResource::retrieveCollections() {

 Collection c;
 c.setParent( Collection::root() );
 c.setRemoteId( Settings::self()->path() );
 c.setName( name() );

 QStringList mimeTypes;
 mimeTypes << "text/directory";
 c.setContentMimeTypes( mimeTypes );

 Collection::List list;
 list << c;
 collectionsRetrieved( list );

}

The code creates a top level collection, i.e. its parent collection is Akonadi's root collection, sets the configured path as its remote identifier (so we could eventually map it back to our "backend" location) and uses our resource name as the user visible collection name.

Since our resource will be providing contact data, we need to set the respective MIME type to indicate which kind of data our collection will hold.

Finally the fully setup collection is sent to Akonadi.

Retrieving Items

Retrieving items for a specific collection is similar to listing the files of a specific directory. Conveniently our backend is a directory, so we can map this directly.

There are several methods to implement item retrieval, e.g. synchronous or asynchronous, all items in one go or in patches, etc. For the scope of the tutorial we choose the easiest combination, i.e. synchronously provide all items in one go. Exercise: Use KDirLister to do this asynchronously and in patches.

First we need another include directive:

1. include <QtCore/QDir>

Then we implement retrieveItems: void VCardDirResource::retrieveItems( const Akonadi::Collection &collection ) {

 // our collections have the mapped path as their remote identifier
 const QString path = collection.remoteId();

 QDir dir( path );

 QStringList filters;
 filters << QLatin1String( "*.vcf" );
 const QStringList fileList = dir.entryList( filters, QDir::Files );

 Item::List items;
 foreach( const QString &file, fileList ) {
   Item item( QLatin1String( "text/directory" ) );
   item.setRemoteId( path + QLatin1Char( '/' ) + file );

   items << item;
 }

 itemsRetrieved( items );

}

Our earlier decision to use the directory's path as the collection's remote identifier conveniently allows us to retrieve the path from the given collection.

We then list all vCard files in that directory and create one Akonadi item for each one, this time using the path plus the file's name as the remote identifier.

Note: This rather primitive implementation assumes that all files with the extension vcf are indeed vCard files and contain only one vCard each.

Finally the whole list of items is sent to Akonadi.

Retrieving Item Data

Continuing our file system analogy, retrieving a specific item's data is similar to reading a specific file's data or its associated meta data. So we have again the convenience of a direct mapping between Akonadi and backend functionality.

Since our backend items are vCard files, we need to parse them into data structures which we can then use as item payloads.

KDE's class for holding contact data is KABC::Addressee and we can use KABC::VCardConverter for file parsing.

First we need another set of includes:

1. include <kabc/addressee.h>
2. include <kabc/vcardconverter.h>

Then we implement the retrieveItem method: bool VCardDirResource::retrieveItem( const Akonadi::Item &item, const QSet<QByteArray> &parts ) {

 Q_UNUSED( parts );

 const QString fileName = item.remoteId();

 QFile file( fileName );
 if ( !file.open( QFile::ReadOnly ) )
   return false;

 const QByteArray data = file.readAll();
 if ( file.error() != QFile::NoError )
   return false;

 KABC::VCardConverter converter;
 KABC::Addressee addressee = converter.parseVCard( data );
 if ( addressee.isEmpty() )
   return false;

 Item newItem( item );
 newItem.setPayload<KABC::Addressee>( addressee );

 itemRetrieved( newItem );
 return true;

}

And additionally we need to edit CMakeLists.txt to make it link the library for the KABC classes: target_link_libraries(akonadi_vcarddir_resource ${KDE4_AKONADI_LIBS} ${QT_QTCORE_LIBRARY} ${QT_QTDBUS_LIBRARY} ${KDE4_KDECORE_LIBS} ${KDE4_KABC_LIBS})

Again aided by our decision what to use as the item's remote identifier, we can directly use it to open the respective vCard file. After parsing the data we create a new item object, use the given item to initialize it, set the contact data object as its payload and send it to Akonadi.

Note: Since we need the full vCard data for parsing, we ignore the parts parameter and always retrieve the full payload.

Item Changes

All Akonadi clients, e.g. end user applications, agents, etc., can at any time add items to collections, change item data and remove items from collections. If such a change happens in the collection tree of a resource, the resource should properly make the respective change on its backend.

Exercise: Add handling for collection changes, e.g. create subdirectories when child collections have been created.

Adding Items

On order to handle items being added to one of our collections, we need to implement the method itemAdded.

First we need another include directive for a helper class:

1. include <krandom.h>

Now we can implement itemAdded like this: void VCardDirResource::itemAdded( const Akonadi::Item &item, const Akonadi::Collection &collection ) {

 const QString path = collection.remoteId();

 KABC::Addressee addressee;
 if ( item.hasPayload<KABC::Addressee>() )
   addressee = item.payload<KABC::Addressee>();

 if ( addressee.uid().isEmpty() )
   addressee.setUid( KRandom::randomString( 10 ) );

 QFile file( path + QLatin1Char( '/' ) + addressee.uid() + QLatin1String( ".vcf" ) );

 if ( !file.open( QFile::WriteOnly ) )
   return;

 KABC::VCardConverter converter;
 file.write( converter.createVCard( addressee ) );
 if ( file.error() != QFile::NoError )
   return;

 Item newItem( item );
 newItem.setRemoteId( file.fileName() );
 newItem.setPayload<KABC::Addressee>( addressee );

 changeCommitted( newItem );

}

As usual we get the path of the directory a specific collection maps to from the collection's remote identifier.

Then we check if the newly added item is already equiped with a payload, in our case a KABC::Addressee object. In either case we ensure that the object has an unique identifier by which we then use as the base name for the vCard file.

Finally we let Akonadi know that we have processed the item change and which remote identifier our backend has assigned to it.

Modifying Items

In our case handling item modifications is almost the same as handling item adding, however more sophisticated resource will most likely do different things depending on the parts parameter.

void VCardDirResource::itemChanged( const Akonadi::Item &item, const QSet<QByteArray> &parts ) {

 Q_UNUSED( parts );

 const QString fileName = item.remoteId();

 KABC::Addressee addressee;
 if ( item.hasPayload<KABC::Addressee>() )
   addressee = item.payload<KABC::Addressee>();

 if ( addressee.uid().isEmpty() )
   addressee.setUid( KRandom::randomString( 10 ) );

 QFile file( fileName );

 if ( !file.open( QFile::WriteOnly ) )
   return;

 KABC::VCardConverter converter;
 file.write( converter.createVCard( addressee ) );
 if ( file.error() != QFile::NoError )
   return;

 Item newItem( item );
 newItem.setPayload<KABC::Addressee>( addressee );

 changeCommitted( newItem );

}

Removing Items

Since we have a one-to-one mapping of items to files, an item removal is as simple as removing the respective file:

void VCardDirResource::itemRemoved( const Akonadi::Item &item ) {

 Q_UNUSED( item );

 const QString fileName = item.remoteId();

 QFile::remove( fileName );

 changeCommitted( item );

}

Backend Changes

Of course changes to collections and items might also happen on the backend and in cases where the backend can send out change notifications, the resource can map these changes directly into its collection tree.

The APIs for that are exactly the same which any other client would use, i.e. Akonadi's job classes.

Exercise: Use KDirWatch to get notified about file and directory changes and modify the Akonadi storage accordingly.

Testing

TODO: Describe basic setup for manual testing. Link to tutorial about using the test suite Igor Trindade Oliveira if working on as a GSoC project.