1/*
2 This file is part of libkabc.
3 Copyright (c) 2001 Cornelius Schumacher <schumacher@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KABC_ADDRESSBOOK_H
22#define KABC_ADDRESSBOOK_H
23
24#include "kabc_export.h"
25
26#include "addressee.h"
27#include "field.h"
28
29#include "kresources/manager.h"
30
31#include <QtCore/QObject>
32#include <QtCore/QList>
33
34namespace KABC {
35
36class DistributionList;
37class ErrorHandler;
38class Resource;
39class Ticket;
40
41/**
42 @short Address Book
43
44 This class provides access to a collection of address book entries.
45 */
46class KABC_DEPRECATED_EXPORT AddressBook : public QObject
47{
48 Q_OBJECT
49
50 friend KABC_EXPORT QDataStream &operator<<( QDataStream &lhs,
51 const AddressBook &rhs );
52 friend KABC_EXPORT QDataStream &operator>>( QDataStream &lhs,
53 AddressBook &rhs );
54 friend class StdAddressBook;
55
56 public:
57 class ConstIterator;
58
59 /**
60 @short Address Book Iterator
61
62 This class provides an iterator for address book entries.
63 */
64 class KABC_DEPRECATED_EXPORT Iterator //krazy:exclude=dpointer
65 {
66 friend class AddressBook;
67 friend class ConstIterator;
68 public:
69 /**
70 Default constructor
71 */
72 Iterator();
73
74 /**
75 Copy constructor
76 */
77 Iterator( const Iterator & );
78 ~Iterator();
79
80 /**
81 Assignment operator. Assignes the given iterator to @c *this.
82
83 @return this iterator, @c *this
84 */
85 Iterator &operator=( const Iterator & );
86
87 /**
88 Constant Dereference operator.
89 @note For invalid iterators, the result is undefined.
90
91 @return the @c const Addressee object the iterator points to.
92 */
93 const Addressee &operator*() const;
94
95 /**
96 Dereference operator.
97 @note For invalid iterators, the result is undefined.
98
99 @return the Addressee object the iterator points to.
100 */
101 Addressee &operator*();
102
103 /**
104 Arrow Dereference operator, provided for convenience.
105 @note For invalid iterators, the result is undefined.
106
107 @return the Addressee object the iterator points to.
108 */
109 Addressee *operator->();
110
111 /**
112 Preincrement operator. Advances the iterator by one.
113
114 @return this iterator, @c *this
115 */
116 Iterator &operator++();
117
118 /**
119 Postincrement operator. Advances the iterator by one.
120 @note This function does not copy the iterator object.
121
122 @return this iterator, @c *this
123 */
124 Iterator &operator++(int);
125
126 /**
127 Predecrement operator. Decreases the iterator by one.
128
129 @return this iterator, @c *this
130 */
131 Iterator &operator--();
132
133 /**
134 Postdecrement operator. Decreases the iterator by one.
135 @note This function does not copy the iterator object.
136
137 @return this iterator, @c *this
138 */
139 Iterator &operator--(int);
140
141 /**
142 Equality operator. Compares this iterator to @p it
143
144 @param it the iterator to compare this iterator to
145 @return @c true if both iterators are equal,
146 @c false otherwise
147 */
148 bool operator==( const Iterator &it ) const;
149
150 /**
151 Inequality operator. Compares this iterator to @p it
152
153 @param it the iterator to compare this iterator to
154 @return @c true if the iterators are not equal,
155 @c false otherwise
156 */
157 bool operator!=( const Iterator &it ) const;
158
159 private:
160 struct IteratorData;
161 IteratorData *const d;
162 };
163
164 /**
165 @short Address Book Const Iterator
166
167 This class provides a const iterator for address book entries.
168 */
169 class KABC_DEPRECATED_EXPORT ConstIterator //krazy:exclude=dpointer
170 {
171 friend class AddressBook;
172 public:
173 /**
174 * Default constructor
175 */
176 ConstIterator();
177
178 /**
179 Copy constructor
180 */
181 ConstIterator( const ConstIterator & );
182
183#ifndef QT_STRICT_ITERATORS
184 /**
185 Copy constructor. Constructs a ConstIterator from
186 an non-@c const Iterator
187 */
188 ConstIterator( const Iterator & );
189#endif
190
191 ~ConstIterator();
192
193 /**
194 Assignment operator. Assignes the given iterator to @c *this.
195
196 @return this iterator, @c *this
197 */
198 ConstIterator &operator=( const ConstIterator & );
199
200 /**
201 Constant Dereference operator.
202 @note For invalid iterators, the result is undefined.
203 @note Unlike in Iterator, there is no non-constant
204 dereference operator.
205
206 @return the @c const Addressee object the iterator points to.
207 */
208 const Addressee &operator*() const;
209
210 /**
211 Arrow Dereference operator, provided for convenience.
212 @note For invalid iterators, the result is undefined.
213
214 @return the Addressee object the iterator points to.
215 */
216 const Addressee *operator->() const;
217
218 /**
219 Preincrement operator. Advances the iterator by one.
220
221 @return this iterator, @c *this
222 */
223 ConstIterator &operator++();
224
225 /**
226 Postincrement operator. Advances the iterator by one.
227 @note This function does not copy the iterator object.
228
229 @return this iterator, @c *this
230 */
231 ConstIterator &operator++(int);
232
233 /**
234 Predecrement operator. Decreases the iterator by one.
235
236 @return this iterator, @c *this
237 */
238 ConstIterator &operator--();
239
240 /**
241 Postdecrement operator. Decreases the iterator by one.
242 @note This function does not copy the iterator object.
243
244 @return this iterator, @c *this
245 */
246 ConstIterator &operator--(int);
247
248 /**
249 Equality operator. Compares this iterator to @p it
250
251 @param it the iterator to compare this iterator to
252 @return @c true if both iterators are equal,
253 @c false otherwise
254 */
255 bool operator==( const ConstIterator &it ) const;
256
257 /**
258 Inequality operator. Compares this iterator to @p it
259
260 @param it the iterator to compare this iterator to
261 @return @c true if the iterators are not equal,
262 @c false otherwise
263 */
264 bool operator!=( const ConstIterator &it ) const;
265
266 private:
267 struct ConstIteratorData;
268 ConstIteratorData *const d;
269 };
270
271 /**
272 Typedef for STL style iterator
273 */
274 typedef Iterator iterator;
275
276 /**
277 Typedef for STL style iterator
278 */
279 typedef ConstIterator const_iterator;
280
281 /**
282 Constructs an address book object.
283 You have to add the resources manually before calling load().
284 */
285 AddressBook();
286
287 /**
288 Constructs an address book object.
289 The resources are loaded automatically.
290
291 @param config The config file which contains the resource settings.
292 */
293 AddressBook( const QString &config );
294
295 /**
296 Destructor.
297 */
298 virtual ~AddressBook();
299
300 /**
301 Requests a ticket for saving the addressbook. Calling this function locks
302 the addressbook for all other processes. You need the returned ticket
303 object for calling the save() function.
304
305 @param resource A pointer to the resource which shall be locked. If 0,
306 the default resource is locked.
307 @return 0 if the resource is already locked or a valid save ticket
308 otherwise.
309 @see save()
310 */
311 Ticket *requestSaveTicket( Resource *resource = 0 );
312
313 /**
314 Releases the ticket requested previously with requestSaveTicket().
315 Call this function, if you want to release a ticket without saving.
316
317 @param ticket the save ticket acquired with requestSaveTicket()
318 */
319 void releaseSaveTicket( Ticket *ticket );
320
321 /**
322 Loads all addressees synchronously.
323
324 @return Whether the loading was successfully.
325 */
326 bool load();
327
328 /**
329 Loads all addressees asynchronously. This function returns immediately
330 and emits the addressBookChanged() signal as soon as the loading has
331 finished.
332
333 @return Whether the synchronous part of loading was successfully.
334 */
335 bool asyncLoad();
336
337 /**
338 Saves all addressees of one resource synchronously. If the save is
339 successful the ticket is deleted.
340
341 @param ticket The ticket returned by requestSaveTicket().
342 @return Whether the saving was successfully.
343 */
344 bool save( Ticket *ticket );
345
346 /**
347 Saves all addressees of one resource asynchronously. If the save is
348 successful the ticket is deleted.
349
350 @param ticket The ticket returned by requestSaveTicket().
351 @return Whether the synchronous part of saving was successfully.
352 */
353 bool asyncSave( Ticket *ticket );
354
355 /**
356 Returns an iterator pointing to the first addressee of address book.
357 This iterator equals end() if the address book is empty.
358 */
359 ConstIterator begin() const;
360 ConstIterator constBegin() const { return begin(); }
361
362 /**
363 This is an overloaded member function, provided for convenience. It
364 behaves essentially like the above function.
365 */
366 Iterator begin();
367
368 /**
369 Returns an iterator pointing to the last addressee of address book.
370 This iterator equals begin() if the address book is empty.
371 */
372 ConstIterator end() const;
373 ConstIterator constEnd() const { return end(); }
374
375 /**
376 This is an overloaded member function, provided for convenience. It
377 behaves essentially like the above function.
378 */
379 Iterator end();
380
381 /**
382 Removes all addressees from the address book.
383 */
384 void clear();
385
386 /**
387 Insert an addressee into the address book. If an addressee with the same
388 unique id already exists, it is replaced by the new one, otherwise it is
389 appended.
390
391 @param addr The addressee which shall be insert.
392 */
393 void insertAddressee( const Addressee &addr );
394
395 /**
396 Removes an addressee from the address book.
397
398 @param addr The addressee which shall be removed.
399 */
400 void removeAddressee( const Addressee &addr );
401
402 /**
403 This is an overloaded member function, provided for convenience. It
404 behaves essentially like the above function.
405
406 @param it An iterator pointing to the addressee which shall be removed.
407 */
408 void removeAddressee( const Iterator &it );
409
410 /**
411 Returns an iterator pointing to the specified addressee. It will return
412 end() if no addressee matched.
413
414 @param addr The addressee you are looking for.
415 */
416 Iterator find( const Addressee &addr );
417
418 /**
419 Returns an iterator pointing to the specified addressee. It will return
420 end() if no addressee matched.
421
422 @param addr The addressee you are looking for.
423 */
424 ConstIterator find( const Addressee &addr ) const;
425
426 /**
427 Searches an addressee with the specified unique identifier.
428
429 @param uid The unique identifier you are looking for.
430 @return The addressee with the specified unique identifier or an
431 empty addressee.
432 */
433 Addressee findByUid( const QString &uid ) const;
434
435 /**
436 Returns a list of all addressees in the address book.
437 */
438 Addressee::List allAddressees() const;
439
440 /**
441 Searches all addressees which match the specified name.
442
443 @param name The name you are looking for.
444 @return A list of all matching addressees.
445 */
446 Addressee::List findByName( const QString &name ) const;
447
448 /**
449 Searches all addressees which match the specified email address.
450
451 @param email The email address you are looking for.
452 @return A list of all matching addressees.
453 */
454 Addressee::List findByEmail( const QString &email ) const;
455
456 /**
457 Searches all addressees which belongs to the specified category.
458
459 @param category The category you are looking for.
460 @return A list of all matching addressees.
461 */
462 Addressee::List findByCategory( const QString &category ) const;
463
464 /**
465 Creates a distribution list with a given @p name storing it in a
466 given @p resource
467
468 @note The newly created list will be added to the addressbook
469 automatically on creation.
470
471 @param name The localized name of the new distribution list.
472 @param resource The resource which should save the list. If @c 0
473 (default) the addressbook's standard resource will be used.
474
475 @see standardResource()
476 */
477 DistributionList *createDistributionList( const QString &name, Resource *resource = 0 );
478
479 /**
480 Removes a distribution @p list from its associated resource.
481
482 @param list The list to remove.
483 */
484 void removeDistributionList( DistributionList *list );
485
486 /**
487 Returns a distribution list for the given @p identifier or @c 0
488
489 @param identifier The ID of the list for look for.
490 */
491 DistributionList *findDistributionListByIdentifier( const QString &identifier );
492
493 /**
494 Returns a distribution list with the given @p name or @c 0
495
496 @param name The localized name of the list for look for.
497 @param caseSensitivity Whether to do string matching case sensitive or
498 case insensitive. Default is @c Qt::CaseSensitive
499 */
500 DistributionList *findDistributionListByName(
501 const QString &name,
502 Qt::CaseSensitivity caseSensitivity = Qt::CaseSensitive );
503
504 /**
505 Returns a list of all distribution lists of all resources of this
506 address book
507 */
508 QList<DistributionList*> allDistributionLists();
509
510 /**
511 Returns a list of names of all distribution lists of all resources
512 of this address book.
513
514 Convenience function, equal to iterate over the list returned
515 by allDistributionLists()
516 */
517 QStringList allDistributionListNames() const;
518
519 /**
520 Returns a string identifying this addressbook. The identifier is
521 created by concatenation of the resource identifiers.
522 */
523 virtual QString identifier() const;
524
525 /**
526 Returns a list of all Fields known to the address book which are
527 associated with the given field category.
528 */
529 Field::List fields( int category = Field::All ) const;
530
531 /**
532 Add custom field to address book.
533
534 @param label User visible label of the field.
535 @param category Ored list of field categories.
536 @param key Identifier used as key for reading and writing the field.
537 @param app String used as application key for reading and writing
538 the field.
539 */
540 bool addCustomField( const QString &label, int category = Field::All,
541 const QString &key = QString(),
542 const QString &app = QString() ) const;
543
544 /**
545 Adds a resource to the address book.
546
547 @param resource The resource you want to add.
548 @return Whether opening the resource was successfully.
549 */
550 bool addResource( Resource *resource );
551
552 /**
553 Removes a resource from the address book.
554
555 @param resource The resource you want to remove.
556 @return Whether closing the resource was successfully.
557 */
558 bool removeResource( Resource *resource );
559
560 /**
561 Returns a list of all resources.
562 */
563 QList<Resource*> resources() const;
564
565 /**
566 Sets the @p ErrorHandler, that is used by error() to
567 provide GUI independent error messages.
568
569 @param errorHandler The error handler you want to use.
570 */
571 void setErrorHandler( ErrorHandler *errorHandler );
572
573 /**
574 Shows GUI independent error messages.
575
576 @param msg The error message that shall be displayed.
577 */
578 void error( const QString &msg );
579
580 /**
581 Used for debug output. This function prints out the list
582 of all addressees to kDebug(5700).
583 */
584 void dump() const;
585
586 /**
587 Emits the signal addressBookLocked() using @c this as the parameter
588 */
589 void emitAddressBookLocked() { addressBookLocked( this ); }
590 /**
591 Emits the signal addressBookUnlocked() using @c this as the parameter
592 */
593 void emitAddressBookUnlocked() { addressBookUnlocked( this ); }
594 /**
595 Emits the signal addressBookChanged() using @c this as the parameter
596 */
597 void emitAddressBookChanged() { addressBookChanged( this ); }
598
599 /**
600 Returns true when the loading of the addressbook has finished,
601 otherwise false.
602 */
603 bool loadingHasFinished() const;
604
605 Q_SIGNALS:
606 /**
607 Emitted when one of the resources discovered a change in its backend
608 or the asynchronous loading of all resources has finished.
609 You should connect to this signal to update the presentation of
610 the contact data in your application.
611
612 @param addressBook The address book which emitted this signal.
613 */
614 void addressBookChanged( AddressBook *addressBook );
615
616 /**
617 Emitted when one of the resources has been locked for writing.
618
619 @param addressBook The address book which emitted this signal.
620 */
621 void addressBookLocked( AddressBook *addressBook );
622
623 /**
624 Emitted when one of the resources has been unlocked.
625 You should connect to this signal if you want to save your changes
626 to a resource which is currently locked, and want to get notified when
627 saving is possible again.
628
629 @param addressBook The address book which emitted this signal.
630 */
631 void addressBookUnlocked( AddressBook *addressBook );
632
633 /**
634 Emitted when the asynchronous loading of one resource has finished
635 after calling asyncLoad().
636
637 @param resource The resource which emitted this signal.
638 */
639 void loadingFinished( Resource *resource );
640
641 /**
642 Emitted when the asynchronous saving of one resource has finished
643 after calling asyncSave().
644
645 @param resource The resource which emitted this signal.
646 */
647 void savingFinished( Resource *resource );
648
649 protected Q_SLOTS:
650 /**
651 Handles loading success.
652
653 Resource will be removed from the list of those pending for loading
654 and signal loadingFinished() will be emitted.
655 It this has been the last one in this list, signal addressBookChanged()
656 is emitted as well.
657
658 @param resource The resource which has been saved successfully.
659 */
660 void resourceLoadingFinished( Resource *resource );
661
662 /**
663 Handles saving success.
664
665 Resource will be removed from the list of those pending for saving.
666
667 @param resource The resource which has been saved successfully.
668 */
669 void resourceSavingFinished( Resource *resource );
670
671 /**
672 Handles loading errors.
673
674 Resource will be removed from the list of those pending for loading.
675 If this has been the last one in this list, signal addressBookChanged()
676 is emitted.
677
678 @param resource The resource which could not be loaded.
679 @param errMsg The message describing the error. See error()
680 */
681 void resourceLoadingError( Resource *resource, const QString &errMsg );
682
683 /**
684 Handles saving errors.
685
686 Resource will be removed from the list of those pending for saving.
687
688 @param resource The resource which could not be saved.
689 @param errMsg The message describing the error. See error()
690 */
691 void resourceSavingError( Resource *resource, const QString &errMsg );
692
693 protected:
694 /**
695 Sets the resource manager's standard resource.
696
697 Convenience method for resourceManager()->setStandardResource()
698
699 @param resource The resource to use as the standard
700
701 @see standardResource()
702 */
703 void setStandardResource( Resource *resource );
704
705 /**
706 Returns the addressbook resource manager's standard resource.
707
708 Convenience method for resourceManager()->standardResource()
709
710 @see setStandardResource()
711 */
712 Resource *standardResource();
713
714 /**
715 Returns the addressbook's resource manager.
716 */
717 KRES::Manager<Resource> *resourceManager();
718
719 private:
720 class Private;
721 Private *const d;
722};
723
724KABC_EXPORT QDataStream &operator<<( QDataStream &lhs, const AddressBook &rhs );
725KABC_EXPORT QDataStream &operator>>( QDataStream &lhs, AddressBook &rhs );
726
727}
728
729#endif
730