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 | |
34 | namespace KABC { |
35 | |
36 | class DistributionList; |
37 | class ErrorHandler; |
38 | class Resource; |
39 | class Ticket; |
40 | |
41 | /** |
42 | @short Address Book |
43 | |
44 | This class provides access to a collection of address book entries. |
45 | */ |
46 | class 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 | |
724 | KABC_EXPORT QDataStream &operator<<( QDataStream &lhs, const AddressBook &rhs ); |
725 | KABC_EXPORT QDataStream &operator>>( QDataStream &lhs, AddressBook &rhs ); |
726 | |
727 | } |
728 | |
729 | #endif |
730 | |