summaryrefslogtreecommitdiffstats
path: root/kabc/HOWTO
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commitce4a32fe52ef09d8f5ff1dd22c001110902b60a2 (patch)
tree5ac38a06f3dde268dc7927dc155896926aaf7012 /kabc/HOWTO
downloadtdelibs-ce4a32fe52ef09d8f5ff1dd22c001110902b60a2.tar.gz
tdelibs-ce4a32fe52ef09d8f5ff1dd22c001110902b60a2.zip
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
Diffstat (limited to 'kabc/HOWTO')
-rw-r--r--kabc/HOWTO372
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 ;)
+