The address book API [http://api.kde.org/4.x-api/kdepimlibs/kabc/index.html KABC] has been available for application developers for several major version releases of KDE.

+

The address book API [http://api.kde.org/4.x-api/kdepimlibs-apidocs/kabc/html/index.html KABC] has been available for application developers for several major version releases of KDE.

−

Its main entry point for applications is the [http://api.kde.org/4.x-api/kdepimlibs/kabc/classKABC_1_1StdAddressBook.html KABC::StdAddressBook] singleton.

+

Its main entry point for applications is the [http://api.kde.org/4.x-api/kdepimlibs-apidocs/kabc/html/classKABC_1_1StdAddressBook.html KABC::StdAddressBook] singleton.

The most prevelant usage is loading all address book contents synchronously and the working with the loaded data set, e.g. by calling "find" methods or even iterating over the whole contact pool.

The most prevelant usage is loading all address book contents synchronously and the working with the loaded data set, e.g. by calling "find" methods or even iterating over the whole contact pool.

Line 15:

Line 15:

== Common Usage Patterns ==

== Common Usage Patterns ==

−

Most usage patterns involve one of the KABC::AddressBook's "find" methods. Their functionality is now mostly available through [http://api.kde.org/4.x-api/kdepimlibs/akonadi/contact/classAkonadi_1_1ContactSearchJob.html Akonadi::ContactSearchJob]

+

Most usage patterns involve one of the KABC::AddressBook's "find" methods. Their functionality is now mostly available through [http://api.kde.org/4.x-api/kdepimlibs-apidocs/akonadi/contact/html/classAkonadi_1_1ContactSearchJob.html Akonadi::ContactSearchJob]

=== Find By Uid ===

=== Find By Uid ===

Line 21:

Line 21:

A common use case is to look for a contact object by its identifier, e.g. acquired by user selection somewhen in the past.

A common use case is to look for a contact object by its identifier, e.g. acquired by user selection somewhen in the past.

{{tip|Sometimes it is necessary to transport some context from the method which creates the job to the result slot. A convenient way to do this is using the job's [http://doc.qt.nokia.com/latest/qobject.html#setProperty setProperty()] method.}}

{{tip|Sometimes it is necessary to transport some context from the method which creates the job to the result slot. A convenient way to do this is using the job's [http://doc.qt.nokia.com/latest/qobject.html#setProperty setProperty()] method.}}

Line 54:

Line 54:

Another common use case is searching for matching contacts by email address. The code for that with KABC classes is almost identical:

Another common use case is searching for matching contacts by email address. The code for that with KABC classes is almost identical:

−

<code cppqt>

+

<syntaxhighlight lang="cpp-qt">

KABC::AddressBook *addressBook = KABC::StdAddressBook::self();

KABC::AddressBook *addressBook = KABC::StdAddressBook::self();

KABC::Addressee contact = addressBook->findByEmail( emailString );

KABC::Addressee contact = addressBook->findByEmail( emailString );

−

</code>

+

</syntaxhighlight>

Unsurprisingly, the Akonadi code looks also quite similar to the previous use case:

Unsurprisingly, the Akonadi code looks also quite similar to the previous use case:

Another use case for KABC::AddressBook is not directly available in Akonadi:

+

<syntaxhighlight lang="cpp-qt">

+

KABC::AddressBook *addressBook = KABC::StdAddressBook::self();

+

+

KABC::Addressee contact = addressBook->whoAmI();

+

</syntaxhighlight>

+

+

{{Note|Even this had its shortcomings, because this depends on the users adding themselves to the address book and marking the respective entry as "this is me".}}

+

+

Concrete use cases this has been deployed for are getting the user's full name and/or their email address, which might be better served by using KDE's identity management instead, see [http://api.kde.org/4.x-api/kdepimlibs-apidocs/kpimidentities/html/classKPIMIdentities_1_1IdentityManager.html KPIMIdentities::IdentityManager].

+

+

It contains the identity users can configure in the Systemsettings module for personal information, so if there is data yet, the application can just embed the respective KCM in a dialog and let the user configure this centrally for all of KDE.

=== Modifying A Contact ===

=== Modifying A Contact ===

+

+

When using KABC::StdAddressBook, modifying a contact (for example one retrieved by findByUid()) worked like this:

+

<syntaxhighlight lang="cpp-qt">

+

addressBook->insertAddressee( contact );

+

+

KABC::Ticket *ticket = addressBook->requestSaveTicket();

+

if ( !ticket ) {

+

// error

+

} else if ( !addressBook->save( ticket ) ) {

+

// error

+

addressBook->releaseSaveTicket( ticket );

+

}

+

}

+

</syntaxhighlight>

+

+

With Akonadi, the application will need the [http://api.kde.org/4.x-api/kdepimlibs-apidocs/akonadi/html/classAkonadi_1_1Item.html Akonadi::Item] or at least the item's identifier.

The most prevelant usage is loading all address book contents synchronously and the working with the loaded data set, e.g. by calling "find" methods or even iterating over the whole contact pool.

Aside from often needlessly loading the all contacts into memory in every application accessing the address book, the synchronous I/O either meant blocking the application or introducing unexpected re-entrancy when the address book plugins were using nested event loops to process jobs without returning from the called function.

Warning

Akonadi's job based API is capable of doing synchronous execution as well, so one might be tempted to use this instead of the signal/slot approach shown on this page. The recommendation is to only use this as an intermediate step at best, the potential re-entrancy due to the nested event loop can lead to hard to debug problems.

Even this had its shortcomings, because this depends on the users adding themselves to the address book and marking the respective entry as "this is me".

Concrete use cases this has been deployed for are getting the user's full name and/or their email address, which might be better served by using KDE's identity management instead, see KPIMIdentities::IdentityManager.

It contains the identity users can configure in the Systemsettings module for personal information, so if there is data yet, the application can just embed the respective KCM in a dialog and let the user configure this centrally for all of KDE.

With Akonadi, the application will need the Akonadi::Item or at least the item's identifier.
Assuming the contact got retrieved using ContactSearchJob, consider keeping the item or Item::id() around, see ContactSearchJob::items().