diff options
Diffstat (limited to 'kabc/HOWTO')
| -rw-r--r-- | kabc/HOWTO | 372 |
1 files changed, 0 insertions, 372 deletions
diff --git a/kabc/HOWTO b/kabc/HOWTO deleted file mode 100644 index 7b41371b0..000000000 --- a/kabc/HOWTO +++ /dev/null @@ -1,372 +0,0 @@ -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/.trinity/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 ;) - |