TDE core libraries
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

HOWTO 14KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372
  1. The KDE Address Book Framework
  2. ===============================
  3. The KDE address book framework tries to provide an easy to use and powerful
  4. mechanism to handle contacts in all KDE applications.
  5. If you want to make use of it, this small introduction to programming
  6. with libtdeabc may be helpful.
  7. General Concepts
  8. =================
  9. In libtdeabc the storage and management of contacts is devided in 2 layers.
  10. ******************
  11. Management Layer *
  12. ******************
  13. .-------------------.
  14. | TDEABC::AddressBook |
  15. .--------------------------------.
  16. | TDEABC::Addressee | => Iterators
  17. | TDEABC::Addressee |
  18. | TDEABC::Addressee | => Search functions
  19. | ... |
  20. `--------------------------------'
  21. |
  22. - - - - - - - - - - - | - - - - - - - - - - - - -
  23. |
  24. *************** |
  25. Storage Layer * |
  26. *************** | .......................
  27. | . . - Network
  28. .---------------. | . .---------------. .
  29. | ResourceFile |----+-----| ResourceLDAP | .
  30. `---------------' | . `---------------' .
  31. .---------------. | . .---------------. .
  32. | ResourceDir |----+-----| ResourceNet | .
  33. `---------------' . `---------------' .
  34. . .
  35. .......................
  36. The Management Layer
  37. ---------------------
  38. The Management Layer consists of the two classes TDEABC::AddressBook and
  39. TDEABC::Addressee. TDEABC::AddressBook is a container for TDEABC::Addressee objects
  40. and provides 2 kinds of access methods.
  41. 1) Iterators
  42. With iterators you can iterate over each of the contacts of the
  43. address book and perform an action on it
  44. 2) Search functions
  45. With search functions you can search for contacts with special attributes
  46. such as "all contacts with the name 'Harald'"
  47. The class TDEABC::Addressee represents a single contact and contains all data
  48. a vCard could store (as specified in RFC 2426).
  49. The Storage Layer
  50. ------------------
  51. The Storage Layer consists of the class TDEABC::Resource and its derived classes.
  52. These classes are used by TDEABC::AddressBook to load and store the contacts to
  53. the single backends.
  54. At the moment libtdeabc provides 4 types of resources:
  55. 1) ResourceFile
  56. - stores all contacts in a single file
  57. 2) ResourceDir
  58. - stores each contact in its own file with the unique identifier of the
  59. contact as a filename, will all of the files together in one directory
  60. 3) ResourceLDAP
  61. - stores all of the contacts on a LDAP server
  62. 4) ResourceNet
  63. - stores all contacts in a single file, which can be accessable via HTTP,
  64. FTP, Fish, WebDAV, POP3, IMAP or whatever the TDEIO frame work supports
  65. In general the developer does not have to take how to save the single contacts.
  66. He just has to plug one of the above mentioned resources into TDEABC::AddressBook
  67. and perform a save action.
  68. Examples
  69. =========
  70. Like a picture, C/C++ code is worth a 1000 words I'd like to give you a
  71. lot of examples now, how to use libtdeabc for several tasks:
  72. Using TDEABC::StdAddressBook and Iterators
  73. -----------------------------------------
  74. Normally you have to plugin the resources manually into the addressbook object
  75. and call the load() function before you can access the contacts, but there is
  76. a special class TDEABC::StdAddressBook, which loads all resources of the standard
  77. address book of the user automatically. You can use it the following way:
  78. #include <tdeabc/stdaddressbook.h>
  79. 1: TDEABC::AddressBook *ab = TDEABC::StdAddressBook::self();
  80. 2: TDEABC::AddressBook::Iterator it;
  81. 3: for ( it = ab->begin(); it != ab->end(); ++it ) {
  82. 4: TDEABC::Addressee addr = (*it);
  83. 5:
  84. 6: kdDebug() << "Name = " << addr.formattedName() << endl;
  85. 7: }
  86. The above example prints out the names of all the contacts in the user's address
  87. book. In line 1 you retrieve a pointer to the user's standard address book
  88. (provided by TDEABC::StdAddressBook via a singleton design pattern).
  89. In line 2 an iterator is defined, which is used in line 3 to iterate over the
  90. whole address book. The assignment in line 4 is intended only to show more
  91. clearly how iterators function.
  92. You could also use (*it).formattedName() directly. In line 6 the formatted name
  93. of the current contact is printed out to stderr.
  94. As you can see that's all magic, and it's quite easy ;)
  95. Using TDEABC::AddressBook manually
  96. ---------------------------------
  97. In some cases you don't want to load the user's standard address book, but,
  98. for example, just a single vCard. For this purpose you have to use the
  99. class TDEABC::AddressBook and handle the resource stuff manually.
  100. The following code will create a file resource and save a contact into it:
  101. #include <tdeabc/addressbook.h>
  102. #include <tdeabc/resourcefile.h>
  103. 1: TDEABC::AddressBook ab;
  104. 2:
  105. 3: // create a file resource
  106. 4: TDEABC::Resource *res = new TDEABC::ResourceFile( "/home/user/myvcard.vcf", "vcard" );
  107. 5:
  108. 6: if ( !ab.addResource( res ) ) {
  109. 7: kdDebug() << "Unable to open resource" << endl;
  110. 8: return 1;
  111. 9: }
  112. 10:
  113. 11: if ( !ab.load() ) {
  114. 12: kdDebug() << "Unable to load address book!" << endl;
  115. 13: return 2;
  116. 14: }
  117. 15:
  118. 16: TDEABC::Addressee addr;
  119. 17: addr.setNameFromString( "Otto Harald Meyer" );
  120. 18: addr.setBirthday( QDate( 1982, 07, 19 ) );
  121. 19: addr.setNickName( "otto" );
  122. 20: addr.setMailer( "kmail" );
  123. 21:
  124. 22: // TZ
  125. 23: TDEABC::TimeZone tz( 60 ); // takes time shift in minutes as argument
  126. 24: addr.setTimeZone( tz );
  127. 25:
  128. 26: // GEO
  129. 27: TDEABC::Geo geo( 52.5, 13.36 ); // takes latitude and longitude as argument
  130. 28: addr.setGeo( geo );
  131. 29:
  132. 30: addr.setTitle( "dude, the" );
  133. 31: addr.setRole( "developer" );
  134. 32: addr.setOrganization( "KDE e.V." );
  135. 33: addr.setNote( "Yet another senseless note..." );
  136. 34: addr.setUrl( KURL( "http://kaddressbook.org" ) );
  137. 35:
  138. 36: // CLASS
  139. 37: TDEABC::Secrecy secrecy( TDEABC::Secrecy::Confidential );
  140. 38: addr.setSecrecy( secrecy );
  141. 39:
  142. 40: // PHOTO or LOGO
  143. 41: TDEABC::Picture photo;
  144. 42: QImage img;
  145. 43: if ( img.load( "face.png", "PNG" ) ) {
  146. 44: photo.setData( img );
  147. 45: photo.setType( "image/png" );
  148. 46: addr.setPhoto( photo );
  149. 47: }
  150. 48:
  151. 49: addr.insertEmail( "otto@kde.se", true ); // preferred email
  152. 50: addr.insertEmail( "otti@yahoo.com", false );
  153. 51:
  154. 52: // TEL
  155. 53: TDEABC::PhoneNumber phoneHome( "0351 5466738", TDEABC::PhoneNumber::Home );
  156. 54: TDEABC::PhoneNumber phoneWork( "0351 2335411", TDEABC::PhoneNumber::Work );
  157. 55: addr.insertPhoneNumber( phoneHome );
  158. 56: addr.insertPhoneNumber( phoneWork );
  159. 57:
  160. 58: // ADR
  161. 59: TDEABC::Address homeAddr( TDEABC::Address::Home );
  162. 60: homeAddr.setStreet( "Milliwaystreet 42" );
  163. 61: homeAddr.setLocality( "London" );
  164. 62: homeAddr.setRegion( "Saxony" );
  165. 63: homeAddr.setPostalCode( "43435" );
  166. 64: homeAddr.setCountry( "Germany" );
  167. 65: addr.insertAddress( homeAddr );
  168. 66:
  169. 67: addr.insertCategory( "LUG-Dresden-Members" );
  170. 68:
  171. 69: addr.insertCustom( "KADDRESSBOOK", "X-Anniversary", "21.04.2009" );
  172. 70:
  173. 71: ab.insertAddressee( addr ); // will be assigned to the standard resource
  174. 72: // automatically
  175. 73:
  176. 74: TDEABC::Ticket *ticket = ab.requestSaveTicket( res );
  177. 75: if ( !ticket ) {
  178. 76: kdError() << "Resource is locked by other application!" << endl;
  179. 77: } else {
  180. 78: if ( !ab.save( ticket ) ) {
  181. 79: kdError() << "Saving failed!" << endl;
  182. 80: ab.releaseSaveTicket( ticket );
  183. 81: }
  184. 82:
  185. 83: }
  186. 84:
  187. 85: return 0;
  188. In line 1 the TDEABC::AddressBook is created. In line 4 you creat the
  189. TDEABC::ResourceFile (which will handle the loading/saving).
  190. The resource takes 2 arguments, the first is the file name and the
  191. second one the file format. At the moment libtdeabc supports two file formats:
  192. 1) vCard, as specified in RFC 2426
  193. 2) Binary, which increases performance during loading and saving
  194. In line 6 we try to plug the resource into the addressbook. The addressbook
  195. class tries to open the resource immediately and returns whether opening was
  196. successful. We add here only one resource, but you can add as many resources
  197. as you want.
  198. In line 11 we try to load all contacts from the backends into the address book.
  199. As before, it returns whether opening was successful.
  200. In line 16 a TDEABC::Addressee is created, which we will fill now with data,
  201. before inserting it into the TDEABC::AddressBook.
  202. The setNameFromString() function in the following line takes a string as
  203. argument and tries to parse it into the single name components such as: given
  204. name, family name, additional names, honoric prefix and honoric suffix.
  205. You can set these values manually as well by calling
  206. addr.setGivenName( "Otto" );
  207. and
  208. addr.setFamilyName( "Meyer" );
  209. etc. etc.
  210. In line 23 we use the class TDEABC::TimeZone to store the timezone. This class
  211. takes the time shift in minutes.
  212. In line 27 the TDEABC::Geo class is used for storing the geographical
  213. information. The arguments are the latitude and longitude as float values.
  214. TDEABC::Secrecy in line 37 represents the CLASS entity of a vCard and can take
  215. TDEABC::Secrecy::Public, TDEABC::Secrecy::Private or TDEABC::Secrecy::Confidential
  216. as argument.
  217. In line 41 we make use of TDEABC::Picture class to store the photo of the
  218. contact. This class can contain either an URL or the raw image data in form
  219. of a QImage, in this example we use the latter.
  220. In line 43 we try to load the image "face.png" from the local directory and
  221. assign this QImage to the TDEABC::Picture class via the setData() function.
  222. Additionally we set the type of the picture to "image/png".
  223. From 49 - 50 we insert 2 email addresses with the first one as preferred
  224. (second argument is true).
  225. In 53 and the following 3 lines we add two telephone numbers. For this purpose
  226. libtdeabc provides the TDEABC::PhoneNumber class, which takes the phone number in
  227. string representation as first argument and the type as second. The types can
  228. be combined, so 'TDEABC::PhoneNumber::Home | TDEABC::PhoneNumber::Fax' would be
  229. the Home Fax.
  230. In line 59 we create a TDEABC::Address object and set the single parts in the
  231. following lines.
  232. In line 67 we assign the contact to a special category.
  233. A contact can also contain custom entries, which are not specified in the API,
  234. so you can add custom values with insertCustom() as shown in line 69.
  235. The first argument of this function should be the name of the application, so
  236. 2 applications which use the same custom entry accidentally, do not overwrite
  237. the data for each other. The second argument contains the name of the
  238. custom entry and the third argument the value in string representation.
  239. In line 71 we finally insert the TDEABC::Addressee object into the
  240. TDEABC::AddressBook. Since we have only one resource loaded, the contact is
  241. automatically assigned to this resource. If you have several writeable
  242. resources loaded, you should ask the user which resource the contact shall
  243. belong to and assign the selected resource to the contact with
  244. TDEABC::Addressee.setResource( TDEABC::Resource *resource );
  245. before inserting it into the address book.
  246. To prevent multiple access to one resource and possible resulting data loss
  247. we have to lock the resource before saving our changes.
  248. For this purpose TDEABC::AddressBook provides the function
  249. requestSaveTicket( TDEABC::Resource* )
  250. which takes a pointer to the resource which shall be saved as argument and
  251. returns a so called 'Save Ticket' if locking succeeded or a null pointer
  252. if the resource is already locked by another application.
  253. So when we retrieved a valid ticket in line 74, we try to save our changes in
  254. line 78.
  255. The TDEABC::AddressBook::save() function takes the save ticket as argument and
  256. returns whether saving succeeded. It also releases the save ticket when successful.
  257. Important!
  258. If the save() call fails, you have to release the save ticket manually, as is
  259. done in line 80, otherwise possible locks, created by the resources, won't be
  260. removed.
  261. You can see also, that manual use is quite easy for the TDEABC::AddressBook class
  262. and for the ResourceFile. For more information about the API of TDEABC::Addressee
  263. please take a look at the official API documentation or the header files.
  264. Distribution Lists
  265. -------------------
  266. libtdeabc provides so called distribution lists to group contacts. These lists
  267. just store the uid of contacts, so they can be used for every kind of contact
  268. grouping. There are 2 classes which handle the whole distribution list tasks,
  269. TDEABC::DistributionListManager and TDEABC::DistributionList. The first one keeps
  270. track of all available distribution lists and the latter one is the
  271. representation of one list.
  272. #include <tdeabc/distributionlist.h>
  273. #include <tdeabc/stdaddressbook.h>
  274. 1: TDEABC::DistributionListManager manager( TDEABC::StdAddressBook::self() );
  275. 2:
  276. 3: // load the lists
  277. 4: manager.load();
  278. 5:
  279. 6: QStringList listNames = manager.listNames();
  280. 7: QStringList::Iterator it;
  281. 8: for ( it = listNames.begin(); it != listNames.end(); ++it ) {
  282. 9: TDEABC::DistributionList *list = manager.list( *it );
  283. 10: kdDebug() << list->name() << endl;
  284. 11:
  285. 12: QStringList emails = list->emails();
  286. 13: QStringList::Iterator eit;
  287. 14: for ( eit = emails.begin(); eit != emails.end(); ++eit )
  288. 15: kdDebug() << QString( "\t%1" ).arg( (*eit).latin1() ) << endl;
  289. 16: }
  290. In the first line a TDEABC::DistributionListManager is created. The manager takes
  291. a pointer to a TDEABC::AddressBook, because he has to resolve the stored uids to
  292. currently available email addresses.
  293. In line 4 the manager loads all distribution lists from the central config file
  294. $HOME/.trinity/share/apps/tdeabc/distlists.
  295. The next line queries the names of all available distribution lists, which are
  296. used in line 9 to retrieve a pointer to the specific list.
  297. Now that you have a TDEABC::DistributionList object, you can performe the
  298. following actions on it:
  299. - set / get the name
  300. - insert an entry
  301. - remove an entry
  302. - get a list of all email addresses
  303. - get a list of all entries (which includes the uids)
  304. In line 12 we query all email addresses of every resource and print them out.
  305. <tdeabc/distributionlist.h> contains also the declaration for the class
  306. TDEABC::DistributionListWatcher. This class exists only once per application and
  307. its only job is to emit a signal as soon as the distribution list file has
  308. changed. So to make your application aware of changes use the following code:
  309. #include <tdeabc/distributionlist.h>
  310. 1: connect( TDEABC::DistributionListWatcher::self(), SIGNAL( changed() ),
  311. 2: this, SLOT( slotDistributionListChanged() ) );
  312. You see, as usual, easy ;)