Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 372 insertions, 0 deletions

diff --git a/kabc/HOWTO b/kabc/HOWTO
new file mode 100644
index 000000000..37f7ccefe
--- /dev/null
+++ b/kabc/HOWTO
@@ -0,0 +1,372 @@
+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 <kabc/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 <kabc/addressbook.h>
+     #include <kabc/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 <kabc/distributionlist.h>
+     #include <kabc/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/.kde/share/apps/kabc/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.
+
+<kabc/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 <kabc/distributionlist.h>
+
+ 1:  connect( KABC::DistributionListWatcher::self(), SIGNAL( changed() ),
+ 2:           this, SLOT( slotDistributionListChanged() ) );
+
+You see, as usual, easy ;)
+