tdelibs/tdeabc/HOWTO

The KDE Address Book Framework
===============================

The KDE address book framework tries to provide an easy to use and powerful
mechanism to handle contacts in all KDE applications.

If you want to make use of it, this small introduction to programming
with libkabc may be helpful.


General Concepts
=================

In libkabc the storage and management of contacts is devided in 2 layers.

******************
Management Layer *
******************

     .-------------------.
     | KABC::AddressBook |
    .--------------------------------.
    | KABC::Addressee                |  => Iterators
    | KABC::Addressee                |
    | KABC::Addressee                |  => Search functions
    | ...                            |
    `--------------------------------'
                       |
 - - - - - - - - - - - | - - - - - - - - - - - - -
                       |
***************        |
Storage Layer *        |
***************        |  .......................
                       |  .                     . - Network
  .---------------.    |  .  .---------------.  .
  | ResourceFile  |----+-----| ResourceLDAP  |  .
  `---------------'    |  .  `---------------'  .
  .---------------.    |  .  .---------------.  .
  | ResourceDir   |----+-----| ResourceNet   |  .
  `---------------'       .  `---------------'  .
                          .                     .
                          .......................


The Management Layer
---------------------
The Management Layer consists of the two classes KABC::AddressBook and
KABC::Addressee. KABC::AddressBook is a container for KABC::Addressee objects
and provides 2 kinds of access methods.
1) Iterators
    With iterators you can iterate over each of the contacts of the
    address book and perform an action on it

2) Search functions
    With search functions you can search for contacts with special attributes
    such as "all contacts with the name 'Harald'"

The class KABC::Addressee represents a single contact and contains all data
a vCard could store (as specified in RFC 2426).

The Storage Layer
------------------
The Storage Layer consists of the class KABC::Resource and its derived classes.
These classes are used by KABC::AddressBook to load and store the contacts to
the single backends.
At the moment libkabc provides 4 types of resources:
1) ResourceFile
  - stores all contacts in a single file

2) ResourceDir
  - stores each contact in its own file with the unique identifier of the
    contact as a filename, will all of the files together in one directory

3) ResourceLDAP
  - stores all of the contacts on a LDAP server

4) ResourceNet
  - stores all contacts in a single file, which can be accessable via HTTP,
    FTP, Fish, WebDAV, POP3, IMAP or whatever the KIO frame work supports

In general the developer does not have to take how to save the single contacts.
He just has to plug one of the above mentioned resources into KABC::AddressBook
and perform a save action.

Examples
=========
Like a picture, C/C++ code is worth a 1000 words I'd like to give you a
lot of examples now, how to use libkabc for several tasks:


Using KABC::StdAddressBook and Iterators
-----------------------------------------
Normally you have to plugin the resources manually into the addressbook object
and call the load() function before you can access the contacts, but there is
a special class KABC::StdAddressBook, which loads all resources of the standard
address book of the user automatically. You can use it the following way:


     #include <tdeabc/stdaddressbook.h>

 1:  KABC::AddressBook *ab = KABC::StdAddressBook::self();
 2:  KABC::AddressBook::Iterator it;
 3:  for ( it = ab->begin(); it != ab->end(); ++it ) {
 4:    KABC::Addressee addr = (*it);
 5:
 6:    kdDebug() << "Name = " << addr.formattedName() << endl;
 7:  }

The above example prints out the names of all the contacts in the user's address
book. In line 1 you retrieve a pointer to the user's standard address book
(provided by KABC::StdAddressBook via a singleton design pattern).
In line 2 an iterator is defined, which is used in line 3 to iterate over the
whole address book. The assignment in line 4 is intended only to show more
clearly how iterators function.
You could also use (*it).formattedName() directly. In line 6 the formatted name
of the current contact is printed out to stderr.
As you can see that's all magic, and it's quite easy ;)


Using KABC::AddressBook manually
---------------------------------
In some cases you don't want to load the user's standard address book, but,
for example, just a single vCard. For this purpose you have to use the
class KABC::AddressBook and handle the resource stuff manually.
The following code will create a file resource and save a contact into it:


     #include <tdeabc/addressbook.h>
     #include <tdeabc/resourcefile.h>

 1:  KABC::AddressBook ab;
 2:
 3:  // create a file resource
 4:  KABC::Resource *res = new KABC::ResourceFile( "/home/user/myvcard.vcf", "vcard" );
 5:
 6:  if ( !ab.addResource( res ) ) {
 7:    kdDebug() << "Unable to open resource" << endl;
 8:    return 1;
 9:  }
10:
11:  if ( !ab.load() ) {
12:    kdDebug() << "Unable to load address book!" << endl;
13:    return 2;
14:  }
15:
16:  KABC::Addressee addr;
17:  addr.setNameFromString( "Otto Harald Meyer" );
18:  addr.setBirthday( QDate( 1982, 07, 19 ) );
19:  addr.setNickName( "otto" );
20:  addr.setMailer( "kmail" );
21:
22:  // TZ
23:  KABC::TimeZone tz( 60 );  // takes time shift in minutes as argument
24:  addr.setTimeZone( tz );
25:
26:  // GEO
27:  KABC::Geo geo( 52.5, 13.36 ); // takes latitude and longitude as argument
28:  addr.setGeo( geo );
29:
30:  addr.setTitle( "dude, the" );
31:  addr.setRole( "developer" );
32:  addr.setOrganization( "KDE e.V." );
33:  addr.setNote( "Yet another senseless note..." );
34:  addr.setUrl( KURL( "http://kaddressbook.org" ) );
35:
36:  // CLASS
37:  KABC::Secrecy secrecy( KABC::Secrecy::Confidential );
38:  addr.setSecrecy( secrecy );
39:
40:  // PHOTO or LOGO
41:  KABC::Picture photo;
42:  QImage img;
43:  if ( img.load( "face.png", "PNG" ) ) {
44:    photo.setData( img );
45:    photo.setType( "image/png" );
46:    addr.setPhoto( photo );
47:  }
48:
49:  addr.insertEmail( "otto@kde.se", true );  // preferred email
50:  addr.insertEmail( "otti@yahoo.com", false );
51:
52:  // TEL
53:  KABC::PhoneNumber phoneHome( "0351 5466738", KABC::PhoneNumber::Home );
54:  KABC::PhoneNumber phoneWork( "0351 2335411", KABC::PhoneNumber::Work );
55:  addr.insertPhoneNumber( phoneHome );
56:  addr.insertPhoneNumber( phoneWork );
57:
58:  // ADR
59:  KABC::Address homeAddr( KABC::Address::Home );
60:  homeAddr.setStreet( "Milliwaystreet 42" );
61:  homeAddr.setLocality( "London" );
62:  homeAddr.setRegion( "Saxony" );
63:  homeAddr.setPostalCode( "43435" );
64:  homeAddr.setCountry( "Germany" );
65:  addr.insertAddress( homeAddr );
66:
67:  addr.insertCategory( "LUG-Dresden-Members" );
68:
69:  addr.insertCustom( "KADDRESSBOOK", "X-Anniversary", "21.04.2009" );
70:
71:  ab.insertAddressee( addr ); // will be assigned to the standard resource
72:                              // automatically
73:
74:  KABC::Ticket *ticket = ab.requestSaveTicket( res );
75:  if ( !ticket ) {
76:    kdError() << "Resource is locked by other application!" << endl;
77:  } else {
78:    if ( !ab.save( ticket ) ) {
79:      kdError() << "Saving failed!" << endl;
80:      ab.releaseSaveTicket( ticket );
81:    }
82:
83:  }
84:
85:  return 0;

In line 1 the KABC::AddressBook is created.  In line 4 you creat the
KABC::ResourceFile (which will handle the loading/saving).
The resource takes 2 arguments, the first is the file name and the
second one the file format. At the moment libkabc supports two file formats:
1) vCard, as specified in RFC 2426
2) Binary, which increases performance during loading and saving

In line 6 we try to plug the resource into the addressbook. The addressbook
class tries to open the resource immediately and returns whether opening was
successful. We add here only one resource, but you can add as many resources
as you want.

In line 11 we try to load all contacts from the backends into the address book.
As before, it returns whether opening was successful.

In line 16 a KABC::Addressee is created, which we will fill now with data,
before inserting it into the KABC::AddressBook.
The setNameFromString() function in the following line takes a string as
argument and tries to parse it into the single name components such as: given
name, family name, additional names, honoric prefix and honoric suffix.
You can set these values manually as well by calling
  addr.setGivenName( "Otto" );
and
  addr.setFamilyName( "Meyer" );
etc. etc.

In line 23 we use the class KABC::TimeZone to store the timezone. This class
takes the time shift in minutes.

In line 27 the KABC::Geo class is used for storing the geographical
information. The arguments are the latitude and longitude as float values.

KABC::Secrecy in line 37 represents the CLASS entity of a vCard and can take
KABC::Secrecy::Public, KABC::Secrecy::Private or KABC::Secrecy::Confidential
as argument.

In line 41 we make use of KABC::Picture class to store the photo of the
contact. This class can contain either an URL or the raw image data in form
of a QImage, in this example we use the latter.

In line 43 we try to load the image "face.png" from the local directory and
assign this QImage to the KABC::Picture class via the setData() function.
Additionally we set the type of the picture to "image/png".

From 49 - 50 we insert 2 email addresses with the first one as preferred
(second argument is true).

In 53 and the following 3 lines we add two telephone numbers. For this purpose
libkabc provides the KABC::PhoneNumber class, which takes the phone number in
string representation as first argument and the type as second. The types can
be combined, so 'KABC::PhoneNumber::Home | KABC::PhoneNumber::Fax' would be
the Home Fax.

In line 59 we create a KABC::Address object and set the single parts in the
following lines.

In line 67 we assign the contact to a special category.

A contact can also contain custom entries, which are not specified in the API,
so you can add custom values with insertCustom() as shown in line 69.
The first argument of this function should be the name of the application, so
2 applications which use the same custom entry accidentally, do not overwrite
the data for each other. The second argument contains the name of the
custom entry and the third argument the value in string representation.

In line 71 we finally insert the KABC::Addressee object into the
KABC::AddressBook. Since we have only one resource loaded, the contact is
automatically assigned to this resource. If you have several writeable
resources loaded, you should ask the user which resource the contact shall
belong to and assign the selected resource to the contact with
  KABC::Addressee.setResource( KABC::Resource *resource );
before inserting it into the address book.

To prevent multiple access to one resource and possible resulting data loss
we have to lock the resource before saving our changes.
For this purpose KABC::AddressBook provides the function
  requestSaveTicket( KABC::Resource* )
which takes a pointer to the resource which shall be saved as argument and
returns a so called 'Save Ticket' if locking succeeded or a null pointer
if the resource is already locked by another application.

So when we retrieved a valid ticket in line 74, we try to save our changes in
line 78.
The KABC::AddressBook::save() function takes the save ticket as argument and
returns whether saving succeeded.  It also releases the save ticket when successful.

Important!
If the save() call fails, you have to release the save ticket manually, as is
done in line 80, otherwise possible locks, created by the resources, won't be
removed.

You can see also, that manual use is quite easy for the KABC::AddressBook class
and for the ResourceFile. For more information about the API of KABC::Addressee
please take a look at the official API documentation or the header files.


Distribution Lists
-------------------
libkabc provides so called distribution lists to group contacts. These lists
just store the uid of contacts, so they can be used for every kind of contact
grouping. There are 2 classes which handle the whole distribution list tasks,
KABC::DistributionListManager and KABC::DistributionList. The first one keeps
track of all available distribution lists and the latter one is the
representation of one list.


     #include <tdeabc/distributionlist.h>
     #include <tdeabc/stdaddressbook.h>

 1:  KABC::DistributionListManager manager( KABC::StdAddressBook::self() );
 2:
 3:  // load the lists
 4:  manager.load();
 5:
 6:  QStringList listNames = manager.listNames();
 7:  QStringList::Iterator it;
 8:  for ( it = listNames.begin(); it != listNames.end(); ++it ) {
 9:    KABC::DistributionList *list = manager.list( *it );
10:    kdDebug() << list->name() << endl;
11:
12:    QStringList emails = list->emails();
13:    QStringList::Iterator eit;
14:    for ( eit = emails.begin(); eit != emails.end(); ++eit )
15:      kdDebug() << QString( "\t%1" ).arg( (*eit).latin1() ) << endl;
16:  }

In the first line a KABC::DistributionListManager is created. The manager takes
a pointer to a KABC::AddressBook, because he has to resolve the stored uids to
currently available email addresses.
In line 4 the manager loads all distribution lists from the central config file
$HOME/.trinity/share/apps/tdeabc/distlists.
The next line queries the names of all available distribution lists, which are
used in line 9 to retrieve a pointer to the specific list.
Now that you have a KABC::DistributionList object, you can performe the
following actions on it:
 - set / get the name
 - insert an entry
 - remove an entry
 - get a list of all email addresses
 - get a list of all entries (which includes the uids)

In line 12 we query all email addresses of every resource and print them out.

<tdeabc/distributionlist.h> contains also the declaration for the class
KABC::DistributionListWatcher. This class exists only once per application and
its only job is to emit a signal as soon as the distribution list file has
changed. So to make your application aware of changes use the following code:


     #include <tdeabc/distributionlist.h>

 1:  connect( KABC::DistributionListWatcher::self(), SIGNAL( changed() ),
 2:           this, SLOT( slotDistributionListChanged() ) );

You see, as usual, easy ;)