@ -18,11 +18,11 @@ Management Layer *
******************
******************
.-------------------.
.-------------------.
| K ABC::AddressBook |
| TDE ABC::AddressBook |
.--------------------------------.
.--------------------------------.
| K ABC::Addressee | => Iterators
| TDE ABC::Addressee | => Iterators
| K ABC::Addressee |
| TDE ABC::Addressee |
| K ABC::Addressee | => Search functions
| TDE ABC::Addressee | => Search functions
| ... |
| ... |
`--------------------------------'
`--------------------------------'
|
|
@ -44,8 +44,8 @@ Storage Layer * |
The Management Layer
The Management Layer
---------------------
---------------------
The Management Layer consists of the two classes K ABC::AddressBook and
The Management Layer consists of the two classes TDE ABC::AddressBook and
KABC::Addressee. KABC::AddressBook is a container for K ABC::Addressee objectsTDEABC::Addressee. TDEABC::AddressBook is a container for TDE ABC::Addressee objects
and provides 2 kinds of access methods.
and provides 2 kinds of access methods.
1) Iterators
1) Iterators
With iterators you can iterate over each of the contacts of the
With iterators you can iterate over each of the contacts of the
@ -55,13 +55,13 @@ and provides 2 kinds of access methods.
With search functions you can search for contacts with special attributes
With search functions you can search for contacts with special attributes
such as "all contacts with the name 'Harald'"
such as "all contacts with the name 'Harald'"
The class K ABC::Addressee represents a single contact and contains all data
The class TDE ABC::Addressee represents a single contact and contains all data
a vCard could store (as specified in RFC 2426).
a vCard could store (as specified in RFC 2426).
The Storage Layer
The Storage Layer
------------------
------------------
The Storage Layer consists of the class K ABC::Resource and its derived classes.
The Storage Layer consists of the class TDE ABC::Resource and its derived classes.
These classes are used by K ABC::AddressBook to load and store the contacts to
These classes are used by TDE ABC::AddressBook to load and store the contacts to
the single backends.
the single backends.
At the moment libkabc provides 4 types of resources:
At the moment libkabc provides 4 types of resources:
1) ResourceFile
1) ResourceFile
@ -79,7 +79,7 @@ At the moment libkabc provides 4 types of resources:
FTP, Fish, WebDAV, POP3, IMAP or whatever the KIO frame work supports
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.
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 K ABC::AddressBook
He just has to plug one of the above mentioned resources into TDE ABC::AddressBook
and perform a save action.
and perform a save action.
Examples
Examples
@ -88,27 +88,27 @@ 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:
lot of examples now, how to use libkabc for several tasks:
Using K ABC::StdAddressBook and Iterators
Using TDE ABC::StdAddressBook and Iterators
-----------------------------------------
-----------------------------------------
Normally you have to plugin the resources manually into the addressbook object
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
and call the load() function before you can access the contacts, but there is
a special class K ABC::StdAddressBook, which loads all resources of the standard
a special class TDE ABC::StdAddressBook, which loads all resources of the standard
address book of the user automatically. You can use it the following way:
address book of the user automatically. You can use it the following way:
#include <tdeabc/stdaddressbook.h>
#include <tdeabc/stdaddressbook.h>
1: KABC::AddressBook *ab = K ABC::StdAddressBook::self();
1: TDEABC::AddressBook *ab = TDE ABC::StdAddressBook::self();
2: K ABC::AddressBook::Iterator it;
2: TDE ABC::AddressBook::Iterator it;
3: for ( it = ab->begin(); it != ab->end(); ++it ) {
3: for ( it = ab->begin(); it != ab->end(); ++it ) {
4: K ABC::Addressee addr = (*it);
4: TDE ABC::Addressee addr = (*it);
5:
5:
6: kdDebug() << "Name = " << addr.formattedName() << endl;
6: kdDebug() << "Name = " << addr.formattedName() << endl;
7: }
7: }
The above example prints out the names of all the contacts in the user's address
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
book. In line 1 you retrieve a pointer to the user's standard address book
(provided by K ABC::StdAddressBook via a singleton design pattern).
(provided by TDE ABC::StdAddressBook via a singleton design pattern).
In line 2 an iterator is defined, which is used in line 3 to iterate over the
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
whole address book. The assignment in line 4 is intended only to show more
clearly how iterators function.
clearly how iterators function.
@ -117,21 +117,21 @@ of the current contact is printed out to stderr.
As you can see that's all magic, and it's quite easy ;)
As you can see that's all magic, and it's quite easy ;)
Using K ABC::AddressBook manually
Using TDE ABC::AddressBook manually
---------------------------------
---------------------------------
In some cases you don't want to load the user's standard address book, but,
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
for example, just a single vCard. For this purpose you have to use the
class K ABC::AddressBook and handle the resource stuff manually.
class TDE ABC::AddressBook and handle the resource stuff manually.
The following code will create a file resource and save a contact into it:
The following code will create a file resource and save a contact into it:
#include <tdeabc/addressbook.h>
#include <tdeabc/addressbook.h>
#include <tdeabc/resourcefile.h>
#include <tdeabc/resourcefile.h>
1: K ABC::AddressBook ab;
1: TDE ABC::AddressBook ab;
2:
2:
3: // create a file resource
3: // create a file resource
4: KABC::Resource *res = new K ABC::ResourceFile( "/home/user/myvcard.vcf", "vcard" );
4: TDEABC::Resource *res = new TDE ABC::ResourceFile( "/home/user/myvcard.vcf", "vcard" );
5:
5:
6: if ( !ab.addResource( res ) ) {
6: if ( !ab.addResource( res ) ) {
7: kdDebug() << "Unable to open resource" << endl;
7: kdDebug() << "Unable to open resource" << endl;
@ -143,18 +143,18 @@ The following code will create a file resource and save a contact into it:
13: return 2;
13: return 2;
14: }
14: }
15:
15:
16: K ABC::Addressee addr;
16: TDE ABC::Addressee addr;
17: addr.setNameFromString( "Otto Harald Meyer" );
17: addr.setNameFromString( "Otto Harald Meyer" );
18: addr.setBirthday( QDate( 1982, 07, 19 ) );
18: addr.setBirthday( QDate( 1982, 07, 19 ) );
19: addr.setNickName( "otto" );
19: addr.setNickName( "otto" );
20: addr.setMailer( "kmail" );
20: addr.setMailer( "kmail" );
21:
21:
22: // TZ
22: // TZ
23: K ABC::TimeZone tz( 60 ); // takes time shift in minutes as argument
23: TDE ABC::TimeZone tz( 60 ); // takes time shift in minutes as argument
24: addr.setTimeZone( tz );
24: addr.setTimeZone( tz );
25:
25:
26: // GEO
26: // GEO
27: K ABC::Geo geo( 52.5, 13.36 ); // takes latitude and longitude as argument
27: TDE ABC::Geo geo( 52.5, 13.36 ); // takes latitude and longitude as argument
28: addr.setGeo( geo );
28: addr.setGeo( geo );
29:
29:
30: addr.setTitle( "dude, the" );
30: addr.setTitle( "dude, the" );
@ -164,11 +164,11 @@ The following code will create a file resource and save a contact into it:
34: addr.setUrl( KURL( "http://kaddressbook.org" ) );
34: addr.setUrl( KURL( "http://kaddressbook.org" ) );
35:
35:
36: // CLASS
36: // CLASS
37: KABC::Secrecy secrecy( K ABC::Secrecy::Confidential );
37: TDEABC::Secrecy secrecy( TDE ABC::Secrecy::Confidential );
38: addr.setSecrecy( secrecy );
38: addr.setSecrecy( secrecy );
39:
39:
40: // PHOTO or LOGO
40: // PHOTO or LOGO
41: K ABC::Picture photo;
41: TDE ABC::Picture photo;
42: QImage img;
42: QImage img;
43: if ( img.load( "face.png", "PNG" ) ) {
43: if ( img.load( "face.png", "PNG" ) ) {
44: photo.setData( img );
44: photo.setData( img );
@ -180,13 +180,13 @@ The following code will create a file resource and save a contact into it:
50: addr.insertEmail( "otti@yahoo.com", false );
50: addr.insertEmail( "otti@yahoo.com", false );
51:
51:
52: // TEL
52: // TEL
53: KABC::PhoneNumber phoneHome( "0351 5466738", K ABC::PhoneNumber::Home );
53: TDEABC::PhoneNumber phoneHome( "0351 5466738", TDE ABC::PhoneNumber::Home );
54: KABC::PhoneNumber phoneWork( "0351 2335411", K ABC::PhoneNumber::Work );
54: TDEABC::PhoneNumber phoneWork( "0351 2335411", TDE ABC::PhoneNumber::Work );
55: addr.insertPhoneNumber( phoneHome );
55: addr.insertPhoneNumber( phoneHome );
56: addr.insertPhoneNumber( phoneWork );
56: addr.insertPhoneNumber( phoneWork );
57:
57:
58: // ADR
58: // ADR
59: KABC::Address homeAddr( K ABC::Address::Home );
59: TDEABC::Address homeAddr( TDE ABC::Address::Home );
60: homeAddr.setStreet( "Milliwaystreet 42" );
60: homeAddr.setStreet( "Milliwaystreet 42" );
61: homeAddr.setLocality( "London" );
61: homeAddr.setLocality( "London" );
62: homeAddr.setRegion( "Saxony" );
62: homeAddr.setRegion( "Saxony" );
@ -201,7 +201,7 @@ The following code will create a file resource and save a contact into it:
71: ab.insertAddressee( addr ); // will be assigned to the standard resource
71: ab.insertAddressee( addr ); // will be assigned to the standard resource
72: // automatically
72: // automatically
73:
73:
74: K ABC::Ticket *ticket = ab.requestSaveTicket( res );
74: TDE ABC::Ticket *ticket = ab.requestSaveTicket( res );
75: if ( !ticket ) {
75: if ( !ticket ) {
76: kdError() << "Resource is locked by other application!" << endl;
76: kdError() << "Resource is locked by other application!" << endl;
77: } else {
77: } else {
@ -214,8 +214,8 @@ The following code will create a file resource and save a contact into it:
84:
84:
85: return 0;
85: return 0;
In line 1 the K ABC::AddressBook is created. In line 4 you creat the
In line 1 the TDE ABC::AddressBook is created. In line 4 you creat the
K ABC::ResourceFile (which will handle the loading/saving).TDE ABC::ResourceFile (which will handle the loading/saving).
The resource takes 2 arguments, the first is the file name and the
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:
second one the file format. At the moment libkabc supports two file formats:
1) vCard, as specified in RFC 2426
1) vCard, as specified in RFC 2426
@ -229,8 +229,8 @@ as you want.
In line 11 we try to load all contacts from the backends into the address book.
In line 11 we try to load all contacts from the backends into the address book.
As before, it returns whether opening was successful.
As before, it returns whether opening was successful.
In line 16 a K ABC::Addressee is created, which we will fill now with data,
In line 16 a TDE ABC::Addressee is created, which we will fill now with data,
before inserting it into the K ABC::AddressBook.
before inserting it into the TDE ABC::AddressBook.
The setNameFromString() function in the following line takes a string as
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
argument and tries to parse it into the single name components such as: given
name, family name, additional names, honoric prefix and honoric suffix.
name, family name, additional names, honoric prefix and honoric suffix.
@ -240,34 +240,34 @@ and
addr.setFamilyName( "Meyer" );
addr.setFamilyName( "Meyer" );
etc. etc.
etc. etc.
In line 23 we use the class K ABC::TimeZone to store the timezone. This class
In line 23 we use the class TDE ABC::TimeZone to store the timezone. This class
takes the time shift in minutes.
takes the time shift in minutes.
In line 27 the K ABC::Geo class is used for storing the geographical
In line 27 the TDE ABC::Geo class is used for storing the geographical
information. The arguments are the latitude and longitude as float values.
information. The arguments are the latitude and longitude as float values.
K ABC::Secrecy in line 37 represents the CLASS entity of a vCard and can takeTDE ABC::Secrecy in line 37 represents the CLASS entity of a vCard and can take
KABC::Secrecy::Public, KABC::Secrecy::Private or K ABC::Secrecy::ConfidentialTDEABC::Secrecy::Public, TDEABC::Secrecy::Private or TDE ABC::Secrecy::Confidential
as argument.
as argument.
In line 41 we make use of K ABC::Picture class to store the photo of the
In line 41 we make use of TDE ABC::Picture class to store the photo of the
contact. This class can contain either an URL or the raw image data in form
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.
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
In line 43 we try to load the image "face.png" from the local directory and
assign this QImage to the K ABC::Picture class via the setData() function.
assign this QImage to the TDE ABC::Picture class via the setData() function.
Additionally we set the type of the picture to "image/png".
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
From 49 - 50 we insert 2 email addresses with the first one as preferred
(second argument is true).
(second argument is true).
In 53 and the following 3 lines we add two telephone numbers. For this purpose
In 53 and the following 3 lines we add two telephone numbers. For this purpose
libkabc provides the K ABC::PhoneNumber class, which takes the phone number in
libkabc provides the TDE ABC::PhoneNumber class, which takes the phone number in
string representation as first argument and the type as second. The types can
string representation as first argument and the type as second. The types can
be combined, so 'KABC::PhoneNumber::Home | K ABC::PhoneNumber::Fax' would be
be combined, so 'TDEABC::PhoneNumber::Home | TDE ABC::PhoneNumber::Fax' would be
the Home Fax.
the Home Fax.
In line 59 we create a K ABC::Address object and set the single parts in the
In line 59 we create a TDE ABC::Address object and set the single parts in the
following lines.
following lines.
In line 67 we assign the contact to a special category.
In line 67 we assign the contact to a special category.
@ -279,25 +279,25 @@ The first argument of this function should be the name of the application, so
the data for each other. The second argument contains the name of the
the data for each other. The second argument contains the name of the
custom entry and the third argument the value in string representation.
custom entry and the third argument the value in string representation.
In line 71 we finally insert the K ABC::Addressee object into the
In line 71 we finally insert the TDE ABC::Addressee object into the
K ABC::AddressBook. Since we have only one resource loaded, the contact isTDE ABC::AddressBook. Since we have only one resource loaded, the contact is
automatically assigned to this resource. If you have several writeable
automatically assigned to this resource. If you have several writeable
resources loaded, you should ask the user which resource the contact shall
resources loaded, you should ask the user which resource the contact shall
belong to and assign the selected resource to the contact with
belong to and assign the selected resource to the contact with
KABC::Addressee.setResource( K ABC::Resource *resource );
TDEABC::Addressee.setResource( TDE ABC::Resource *resource );
before inserting it into the address book.
before inserting it into the address book.
To prevent multiple access to one resource and possible resulting data loss
To prevent multiple access to one resource and possible resulting data loss
we have to lock the resource before saving our changes.
we have to lock the resource before saving our changes.
For this purpose K ABC::AddressBook provides the function
For this purpose TDE ABC::AddressBook provides the function
requestSaveTicket( K ABC::Resource* )
requestSaveTicket( TDE ABC::Resource* )
which takes a pointer to the resource which shall be saved as argument and
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
returns a so called 'Save Ticket' if locking succeeded or a null pointer
if the resource is already locked by another application.
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
So when we retrieved a valid ticket in line 74, we try to save our changes in
line 78.
line 78.
The K ABC::AddressBook::save() function takes the save ticket as argument and
The TDE ABC::AddressBook::save() function takes the save ticket as argument and
returns whether saving succeeded. It also releases the save ticket when successful.
returns whether saving succeeded. It also releases the save ticket when successful.
Important!
Important!
@ -305,8 +305,8 @@ 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
done in line 80, otherwise possible locks, created by the resources, won't be
removed.
removed.
You can see also, that manual use is quite easy for the K ABC::AddressBook class
You can see also, that manual use is quite easy for the TDE ABC::AddressBook class
and for the ResourceFile. For more information about the API of K ABC::Addressee
and for the ResourceFile. For more information about the API of TDE ABC::Addressee
please take a look at the official API documentation or the header files.
please take a look at the official API documentation or the header files.
@ -315,7 +315,7 @@ Distribution Lists
libkabc provides so called distribution lists to group contacts. These 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
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,
grouping. There are 2 classes which handle the whole distribution list tasks,
KABC::DistributionListManager and K ABC::DistributionList. The first one keepsTDEABC::DistributionListManager and TDE ABC::DistributionList. The first one keeps
track of all available distribution lists and the latter one is the
track of all available distribution lists and the latter one is the
representation of one list.
representation of one list.
@ -323,7 +323,7 @@ representation of one list.
#include <tdeabc/distributionlist.h>
#include <tdeabc/distributionlist.h>
#include <tdeabc/stdaddressbook.h>
#include <tdeabc/stdaddressbook.h>
1: KABC::DistributionListManager manager( K ABC::StdAddressBook::self() );
1: TDEABC::DistributionListManager manager( TDE ABC::StdAddressBook::self() );
2:
2:
3: // load the lists
3: // load the lists
4: manager.load();
4: manager.load();
@ -331,7 +331,7 @@ representation of one list.
6: QStringList listNames = manager.listNames();
6: QStringList listNames = manager.listNames();
7: QStringList::Iterator it;
7: QStringList::Iterator it;
8: for ( it = listNames.begin(); it != listNames.end(); ++it ) {
8: for ( it = listNames.begin(); it != listNames.end(); ++it ) {
9: K ABC::DistributionList *list = manager.list( *it );
9: TDE ABC::DistributionList *list = manager.list( *it );
10: kdDebug() << list->name() << endl;
10: kdDebug() << list->name() << endl;
11:
11:
12: QStringList emails = list->emails();
12: QStringList emails = list->emails();
@ -340,14 +340,14 @@ representation of one list.
15: kdDebug() << QString( "\t%1" ).arg( (*eit).latin1() ) << endl;
15: kdDebug() << QString( "\t%1" ).arg( (*eit).latin1() ) << endl;
16: }
16: }
In the first line a K ABC::DistributionListManager is created. The manager takes
In the first line a TDE ABC::DistributionListManager is created. The manager takes
a pointer to a K ABC::AddressBook, because he has to resolve the stored uids to
a pointer to a TDE ABC::AddressBook, because he has to resolve the stored uids to
currently available email addresses.
currently available email addresses.
In line 4 the manager loads all distribution lists from the central config file
In line 4 the manager loads all distribution lists from the central config file
$HOME/.trinity/share/apps/tdeabc/distlists.
$HOME/.trinity/share/apps/tdeabc/distlists.
The next line queries the names of all available distribution lists, which are
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.
used in line 9 to retrieve a pointer to the specific list.
Now that you have a K ABC::DistributionList object, you can performe the
Now that you have a TDE ABC::DistributionList object, you can performe the
following actions on it:
following actions on it:
- set / get the name
- set / get the name
- insert an entry
- insert an entry
@ -358,14 +358,14 @@ following actions on it:
In line 12 we query all email addresses of every resource and print them out.
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
<tdeabc/distributionlist.h> contains also the declaration for the class
K ABC::DistributionListWatcher. This class exists only once per application andTDE ABC::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
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:
changed. So to make your application aware of changes use the following code:
#include <tdeabc/distributionlist.h>
#include <tdeabc/distributionlist.h>
1: connect( K ABC::DistributionListWatcher::self(), SIGNAL( changed() ),
1: connect( TDE ABC::DistributionListWatcher::self(), SIGNAL( changed() ),
2: this, SLOT( slotDistributionListChanged() ) );
2: this, SLOT( slotDistributionListChanged() ) );
You see, as usual, easy ;)
You see, as usual, easy ;)
Timothy Pearson
12 years ago