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.

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.

+

+

See the [http://api.kde.org/4.x-api/kdepimlibs-apidocs/akonadi/html/classAkonadi_1_1ResourceBase.html#_details Resource related API documentation] for developer information not covered in this tutorial.

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.

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.

+

+

For other real-life examples of akonadi resources see projects in [https://projects.kde.org/projects/kde/kdepim-runtime/repository/revisions/master/show/resources /kdepim-runtime/resources] KDE source directory.

{{improve|Add error handling to resource code snippets}}

{{improve|Add error handling to resource code snippets}}

Line 23:

Line 29:

== Preparation ==

== Preparation ==

+

+

The KDE client library for Akonadi provides a base class, [http://api.kde.org/4.x-api/kdepimlibs-apidocs/akonadi/html/classAkonadi_1_1ResourceBase.html Akonadi::ResourceBase], which already implements most of the low level communication between resource and Akonadi server, letting the resource developer concentrate on communication with the backend.

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, or by running '''kapptemplate''' in a terminal window.

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, or by running '''kapptemplate''' in a terminal window.

Line 31:

Line 39:

A look at the generated project directory shows us the following files:

A look at the generated project directory shows us the following files:

−

<code>

+

<syntaxhighlight lang="bash">

akonadi-resources.png

akonadi-resources.png

Messages.sh

Messages.sh

Line 41:

Line 49:

vcarddirresource.cpp

vcarddirresource.cpp

vcarddirresource.h

vcarddirresource.h

−

</code>

+

</syntaxhighlight>

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.

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.

and open the generated project with KDevelop and run the build process from there.

and open the generated project with KDevelop and run the build process from there.

Line 72:

Line 85:

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

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

−

<code ini>

+

<syntaxhighlight lang="ini">

[Desktop Entry]

[Desktop Entry]

Name=Akonadi VCardDir Resource

Name=Akonadi VCardDir Resource

Line 84:

Line 97:

X-Akonadi-Capabilities=Resource

X-Akonadi-Capabilities=Resource

X-Akonadi-Identifier=akonadi_vcarddir_resource

X-Akonadi-Identifier=akonadi_vcarddir_resource

−

</code>

+

</syntaxhighlight>

'''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.

'''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.

Line 95:

Line 108:

The template we are basing our resource on already contains such a file, '''vcarddirresource.kcfg''', and we only have to add a new option for our base directory:

The template we are basing our resource on already contains such a file, '''vcarddirresource.kcfg''', and we only have to add a new option for our base directory:

−

<code xml>

+

<syntaxhighlight lang="xml">

<?xml version="1.0" encoding="UTF-8"?>

<?xml version="1.0" encoding="UTF-8"?>

<kcfg xmlns="http://www.kde.org/standards/kcfg/1.0"

<kcfg xmlns="http://www.kde.org/standards/kcfg/1.0"

Line 113:

Line 126:

</group>

</group>

</kcfg>

</kcfg>

−

</code>

+

</syntaxhighlight>

−

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 {{class|KFileDialog}}

+

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 easier and just use a {{class|KFileDialog}}

+

+

{{warning|This simplification has the side effect that the passed window ID cannot be used as it should. See FAQ section at the end of the tutorial.}}

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

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

−

<code cppqt>

+

<syntaxhighlight lang="cpp-qt">

#include <kfiledialog.h>

#include <kfiledialog.h>

#include <klocalizedstring.h>

#include <klocalizedstring.h>

−

</code>

+

</syntaxhighlight>

To show the dialog on the user's request, we need to modify the resource method <tt>configure</tt> which currently has an empty implementation.

To show the dialog on the user's request, we need to modify the resource method <tt>configure</tt> which currently has an empty implementation.

−

<code cppqt>

+

<syntaxhighlight lang="cpp-qt">

void VCardDirResource::configure( WId windowId )

void VCardDirResource::configure( WId windowId )

{

{

Line 151:

Line 166:

synchronize();

synchronize();

}

}

−

</code>

+

</syntaxhighlight>

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

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

+

+

{{tip|Since there can be more than one resource of a certain type, it is recommended to change the resource name to something that makes them distiguishable. In the case of this example resource it could be the name of the base directory or part of its path}}

== Data Retrieval ==

== Data Retrieval ==

Line 167:

Line 184:

Retrieval of collections is handled in <tt>retrieveCollections</tt>:

Retrieval of collections is handled in <tt>retrieveCollections</tt>:

−

<code cppqt>

+

<syntaxhighlight lang="cpp-qt">

void VCardDirResource::retrieveCollections()

void VCardDirResource::retrieveCollections()

{

{

Line 176:

Line 193:

QStringList mimeTypes;

QStringList mimeTypes;

−

mimeTypes << "text/directory";

+

mimeTypes << QLatin1String("text/directory");

c.setContentMimeTypes( mimeTypes );

c.setContentMimeTypes( mimeTypes );

Line 183:

Line 200:

collectionsRetrieved( list );

collectionsRetrieved( list );

}

}

−

</code>

+

</syntaxhighlight>

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.

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.

Line 190:

Line 207:

Finally the fully set up collection is sent to Akonadi.

Finally the fully set up collection is sent to Akonadi.

+

+

{{tip|You can customize visualization properties of the collection, e.g. icon, by using the [http://api.kde.org/4.x-api/kdepimlibs-apidocs/akonadi/html/classAkonadi_1_1EntityDisplayAttribute.html EntityDisplayAttribute] class}}

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.

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.

Line 295:

Line 314:

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.

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.

+

+

By default, resources are only notified about which items have been changed and which of the parts have been modified.

+

To automatically the get the updated payload we only have to enable this operation mode on the resource's change recorder.

+

+

To do that we need another two include directives

+

+

<syntaxhighlight lang="cpp-qt">

+

#include <akonadi/itemfetchscope.h>

+

#include <akonadi/changerecorder.h>

+

</syntaxhighlight>

+

+

and an additional line in the resource's constructor

+

+

<syntaxhighlight lang="cpp-qt">

+

changeRecorder()->itemFetchScope().fetchFullPayload();

+

</syntaxhighlight>

+

+

This tells the base implementation that each item change should be fetched with full payload before delivering it to the methods covered in the following subsections.

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

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

−

<code cppqt>

+

<syntaxhighlight lang="cpp-qt">

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

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

{

{

Line 395:

Line 432:

changeCommitted( item );

changeCommitted( item );

}

}

−

</code>

+

</syntaxhighlight>

== Backend Changes ==

== Backend Changes ==

Line 407:

Line 444:

== Testing ==

== Testing ==

−

{{improve|Describe basic setup for manual testing. Link to tutorial about using the test suite Igor Trindade Oliveira is working on as a GSoC project.}}

+

The [[Projects/PIM/Akonadi/Testing|Akonadi Test Framework]] allows to create self-contained test environments so developers do not risk impacting their normal Akonadi setup.

+

+

To install new resource to system run (might need root):

+

<syntaxhighlight lang="bash">

+

make install

+

</syntaxhighlight>

+

+

or copy built files manually to the following locations:

+

<syntaxhighlight lang="bash">

+

$KDEDIRS/bin/akonadi_vcarddir_resource

+

$KDEDIRS/share/akonadi/agents/vcarddirresource.desktop

+

</syntaxhighlight>

+

+

where $KDEDIRS points to your KDE installation prefix.

+

+

Then run Akonadi Configuration (search by this keyword in kickoff launcher) and click "Add..." button to add new resource - new resource should be there; or in KAddressBook add new address book - new resource should be available as address book type (restarting akonadi server might help if it does not get into this list immediately).

+

+

{{improve|Create tutorial about using the test suite.}}

+

+

== Frequently Asked Questions and Tips ==

+

+

=== Base Class Methods ===

+

+

==== When is configure() called ====

+

+

[http://api.kde.org/4.x-api/kdepimlibs-apidocs/akonadi/html/classAkonadi_1_1AgentBase.html#88a08911cd0a69934207ef1a154a23ba ResourceBase::configure()] is called under two circumstances.

+

* as part of the resource's creation process: when the Akonadi control process creates a resource, it will also call the resource's '''configure()''' method through D-Bus once the resource has registered itself.

+

+

* when another program explicitly requests it: since '''configure()''' is exposed as a D-Bus method, any other program can call it to request a resource's reconfiguration. End user applications might offer this functionality to allow the user to change resource specific settings.

+

+

==== What is the purpose of the window ID parameter of configure()? ====

+

+

The resource is a program on its own, i.e. it is not the same process as the end user application working with the data provided by the resource.

+

+

In an in-process scenario any configuration UI can specify one of the application's top level widgets as its parent, thus associating the configuration UI with that window.

+

+

Window managing systems such as KDE's KWin use this information to keep new windows from interrupting the user unless they are very likely a consequence of a user's action.

+

+

To make such an association across process boundaries, the calling application can send a platforms specific window identifier over to the resource which in tunr can then use it to specify it as a "parent" for its configuration UI like this:

+

+

<syntaxhighlight lang="cpp-qt">

+

ConfigDialog dialog;

+

KWindowSystem::setMainWindow( &dialog, windowId );

+

</syntaxhighlight>

+

+

See {{class|KWindowSystem}}

+

+

==== Is retrieveItem() called in the order retrieveItems() passes the items? ====

+

+

The purpose of [http://api.kde.org/4.x-api/kdepimlibs-apidocs/akonadi/html/classAkonadi_1_1ResourceBase.html#38d7c3713ed54dedf885d437de1ca11d ResourceBase::retrieveItem()] is to deliver additional item data, i.e. data not yet available in the Akonadi cache.

+

+

This can happen due to several different reasons, only one of them is '''retrieveItems()''' delivering just basic items.

+

+

An implementation should therefore '''always''' treat an invocation of this method as a single incidence unrelated to anything else.

The KDE client library for Akonadi provides a base class, Akonadi::ResourceBase, which already implements most of the low level communication between resource and Akonadi server, letting the resource developer concentrate on communication with the backend.

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, or by running kapptemplate in a terminal window.

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.

A look at the generated project directory shows us the following files:

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.

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:

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 easier and just use a KFileDialog

Warning

This simplification has the side effect that the passed window ID cannot be used as it should. See FAQ section at the end of the tutorial.

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

#include <kfiledialog.h>#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 implementation.

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

Tip

Since there can be more than one resource of a certain type, it is recommended to change the resource name to something that makes them distiguishable. In the case of this example resource it could be the name of the base directory or part of its path

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 set up collection is sent to Akonadi.

Tip

You can customize visualization properties of the collection, e.g. icon, by using the EntityDisplayAttribute class

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.

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.

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.

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.

By default, resources are only notified about which items have been changed and which of the parts have been modified.
To automatically the get the updated payload we only have to enable this operation mode on the resource's change recorder.

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.

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.

Tip

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

Then run Akonadi Configuration (search by this keyword in kickoff launcher) and click "Add..." button to add new resource - new resource should be there; or in KAddressBook add new address book - new resource should be available as address book type (restarting akonadi server might help if it does not get into this list immediately).

as part of the resource's creation process: when the Akonadi control process creates a resource, it will also call the resource's configure() method through D-Bus once the resource has registered itself.

when another program explicitly requests it: since configure() is exposed as a D-Bus method, any other program can call it to request a resource's reconfiguration. End user applications might offer this functionality to allow the user to change resource specific settings.

The resource is a program on its own, i.e. it is not the same process as the end user application working with the data provided by the resource.

In an in-process scenario any configuration UI can specify one of the application's top level widgets as its parent, thus associating the configuration UI with that window.

Window managing systems such as KDE's KWin use this information to keep new windows from interrupting the user unless they are very likely a consequence of a user's action.

To make such an association across process boundaries, the calling application can send a platforms specific window identifier over to the resource which in tunr can then use it to specify it as a "parent" for its configuration UI like this: