Difference between revisions of "Development/AkonadiPorting/AddressBook"

Jump to: navigation, search
(Address book to Akonadi porting: introduction)
 
(Find By Uid)
Line 16: Line 16:
  
 
=== Find By Uid ===
 
=== Find By Uid ===
 +
 +
A common use case is to look for a contact object by its identifier, e.g. acquired by user selection somewhen in the past.
 +
The code to do that usually looks like this:
 +
<code cppqt>
 +
KABC::AddressBook *addressBook = KABC::StdAddressBook::self();
 +
 +
KABC::Addressee contact = addressBook->findByUid( uidString );
 +
</code>
 +
 +
The equivalent using Akonadi API looks like this
 +
<code cppqt>
 +
Akonadi::ContactSearchJob *job = new Akonadi::ContactSearchJob( this );
 +
job->setQuery( Akonadi::ContactSearchJob::ContactUid, uidString );
 +
 +
connect( job, SIGNAL( result( KJob* ) ), SLOT( contactSearchResult( KJob* ) ) );
 +
</code>
 +
and
 +
<code cppqt>
 +
void contactSearchResult( KJob *job )
 +
{
 +
  if ( job->error() != 0 ) {
 +
    // error handling, see job->errorString()
 +
    return;
 +
  }
 +
 +
  Akonadi::ContactSearchJob *searchJob = qobject_cast<Akonadi::ContactSearchJob*>( job );
 +
 +
  const KABC::Addressee::List contacts = searchJob->contacts();
 +
}
 +
</code>
 +
 +
{{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.}}
  
 
=== Find By Email ===
 
=== Find By Email ===

Revision as of 13:57, 20 June 2010


Contents

Development/AkonadiPorting/AddressBook


Introduction

The address book API KABC has been available for application developers for several major version releases of KDE.

Its main entry point for applications is the 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.

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.

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


Common Usage Patterns

Find By Uid

A common use case is to look for a contact object by its identifier, e.g. acquired by user selection somewhen in the past. The code to do that usually looks like this: KABC::AddressBook *addressBook = KABC::StdAddressBook::self();

KABC::Addressee contact = addressBook->findByUid( uidString );

The equivalent using Akonadi API looks like this Akonadi::ContactSearchJob *job = new Akonadi::ContactSearchJob( this ); job->setQuery( Akonadi::ContactSearchJob::ContactUid, uidString );

connect( job, SIGNAL( result( KJob* ) ), SLOT( contactSearchResult( KJob* ) ) ); and void contactSearchResult( KJob *job ) {

 if ( job->error() != 0 ) {
   // error handling, see job->errorString()
   return;
 }
 Akonadi::ContactSearchJob *searchJob = qobject_cast<Akonadi::ContactSearchJob*>( job );
 const KABC::Addressee::List contacts = searchJob->contacts();

}

Ktip.png
 
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 setProperty() method.


Find By Email

Who Am I

Modifying A Contact

Further Reading


KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal