1/*
2 This file is part of libkabc.
3 Copyright (c) 2001 Cornelius Schumacher <schumacher@kde.org>
4 2013 Tobias Koenig <tokoe@kde.org>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21
22#ifndef KABC_ADDRESSEE_H
23#define KABC_ADDRESSEE_H
24
25#include <QtCore/QDateTime>
26#include <QtCore/QStringList>
27#include <QtCore/QSharedDataPointer>
28
29#include <kurl.h>
30
31#include "kabc/address.h"
32#include "kabc/geo.h"
33#include "kabc/key.h"
34#include "kabc/phonenumber.h"
35#include "kabc/picture.h"
36#include "kabc/secrecy.h"
37#include "kabc/sound.h"
38#include "kabc/timezone.h"
39#include "kabc/addresseelist.h" // for typedef QList<Addressee> List;
40
41namespace KABC {
42
43#ifndef KDEPIM_NO_KRESOURCES
44class Resource;
45#endif
46class SortMode;
47
48/**
49 @short address book entry
50
51 This class represents an entry in the address book.
52
53 The data of this class is implicitly shared. You can pass this class by value.
54
55 If you need the name of a field for presenting it to the user you should use
56 the functions ending in Label(). They return a translated string which can be
57 used as label for the corresponding field.
58
59 About the name fields:
60
61 givenName() is the first name and familyName() the last name. In some
62 countries the family name comes first, that's the reason for the
63 naming. formattedName() is the full name with the correct formatting.
64 It is used as an override, when the correct formatting can't be generated
65 from the other name fields automatically.
66
67 realName() returns a fully formatted name(). It uses formattedName, if set,
68 otherwise it constucts the name from the name fields. As fallback, if
69 nothing else is set it uses name().
70
71 name() is the NAME type of RFC2426. It can be used as internal name for the
72 data enty, but shouldn't be used for displaying the data to the user.
73 */
74class KABC_EXPORT Addressee
75{
76 friend KABC_EXPORT QDataStream &operator<<( QDataStream &, const Addressee & );
77 friend KABC_EXPORT QDataStream &operator>>( QDataStream &, Addressee & );
78
79 public:
80 /**
81 A list of addressee objects
82 */
83 typedef AddresseeList List;
84 /**
85 A map from unique identifier to addressee.
86
87 @see uid()
88 */
89 typedef QMap<QString, Addressee> Map;
90
91 /**
92 Construct an empty address book entry.
93 */
94 Addressee();
95
96 /**
97 Destroys the address book entry.
98 */
99 ~Addressee();
100
101 /**
102 Copy constructor.
103 */
104 Addressee( const Addressee & );
105
106 /**
107 Assignment operator.
108
109 @return a reference to @c this
110 */
111 Addressee &operator=( const Addressee & );
112
113 /**
114 Equality operator.
115
116 @return @c true if @c this and the given addressee are equal,
117 otherwise @c false
118 */
119 bool operator==( const Addressee & ) const;
120
121 /**
122 Not-equal operator.
123
124 @return @c true if @c this and the given addressee are not equal,
125 otherwise @c false
126 */
127 bool operator!=( const Addressee & ) const;
128
129 /**
130 Return, if the address book entry is empty.
131 */
132 bool isEmpty() const;
133
134 /**
135 Set unique identifier.
136
137 @param uid the KABC unique identifier
138 */
139 void setUid( const QString &uid );
140
141 /**
142 Return unique identifier.
143 */
144 QString uid() const;
145
146 /**
147 Return translated label for uid field.
148 */
149 static QString uidLabel();
150
151 /**
152 Set name.
153 */
154 void setName( const QString &name );
155
156 /**
157 Return name.
158 */
159 QString name() const;
160
161 /**
162 Return translated label for name field.
163 */
164 static QString nameLabel();
165
166 /**
167 Set formatted name.
168 */
169 void setFormattedName( const QString &formattedName );
170
171 /**
172 Return formatted name.
173 */
174 QString formattedName() const;
175
176 /**
177 Return translated label for formattedName field.
178 */
179 static QString formattedNameLabel();
180
181 /**
182 Set family name.
183 */
184 void setFamilyName( const QString &familyName );
185
186 /**
187 Return family name.
188 */
189 QString familyName() const;
190
191 /**
192 Return translated label for familyName field.
193 */
194 static QString familyNameLabel();
195
196 /**
197 Set given name.
198 */
199 void setGivenName( const QString &givenName );
200
201 /**
202 Return given name.
203 */
204 QString givenName() const;
205
206 /**
207 Return translated label for givenName field.
208 */
209 static QString givenNameLabel();
210
211 /**
212 Set additional names.
213 */
214 void setAdditionalName( const QString &additionalName );
215
216 /**
217 Return additional names.
218 */
219 QString additionalName() const;
220
221 /**
222 Return translated label for additionalName field.
223 */
224 static QString additionalNameLabel();
225
226 /**
227 Set honorific prefixes.
228 */
229 void setPrefix( const QString &prefix );
230
231 /**
232 Return honorific prefixes.
233 */
234 QString prefix() const;
235
236 /**
237 Return translated label for prefix field.
238 */
239 static QString prefixLabel();
240
241 /**
242 Set honorific suffixes.
243 */
244 void setSuffix( const QString &suffix );
245
246 /**
247 Return honorific suffixes.
248 */
249 QString suffix() const;
250
251 /**
252 Return translated label for suffix field.
253 */
254 static QString suffixLabel();
255
256 /**
257 Set nick name.
258 */
259 void setNickName( const QString &nickName );
260
261 /**
262 Return nick name.
263 */
264 QString nickName() const;
265
266 /**
267 Return translated label for nickName field.
268 */
269 static QString nickNameLabel();
270
271 /**
272 Set birthday.
273 */
274 void setBirthday( const QDateTime &birthday );
275
276 /**
277 Return birthday.
278 */
279 QDateTime birthday() const;
280
281 /**
282 Return translated label for birthday field.
283 */
284 static QString birthdayLabel();
285
286 /**
287 Return translated label for homeAddressStreet field.
288 */
289 static QString homeAddressStreetLabel();
290
291 /**
292 Return translated label for homeAddressPostOfficeBox field.
293 */
294 static QString homeAddressPostOfficeBoxLabel();
295
296 /**
297 Return translated label for homeAddressLocality field.
298 */
299 static QString homeAddressLocalityLabel();
300
301 /**
302 Return translated label for homeAddressRegion field.
303 */
304 static QString homeAddressRegionLabel();
305
306 /**
307 Return translated label for homeAddressPostalCode field.
308 */
309 static QString homeAddressPostalCodeLabel();
310
311 /**
312 Return translated label for homeAddressCountry field.
313 */
314 static QString homeAddressCountryLabel();
315
316 /**
317 Return translated label for homeAddressLabel field.
318 */
319 static QString homeAddressLabelLabel();
320
321 /**
322 Return translated label for businessAddressStreet field.
323 */
324 static QString businessAddressStreetLabel();
325
326 /**
327 Return translated label for businessAddressPostOfficeBox field.
328 */
329 static QString businessAddressPostOfficeBoxLabel();
330
331 /**
332 Return translated label for businessAddressLocality field.
333 */
334 static QString businessAddressLocalityLabel();
335
336 /**
337 Return translated label for businessAddressRegion field.
338 */
339 static QString businessAddressRegionLabel();
340
341 /**
342 Return translated label for businessAddressPostalCode field.
343 */
344 static QString businessAddressPostalCodeLabel();
345
346 /**
347 Return translated label for businessAddressCountry field.
348 */
349 static QString businessAddressCountryLabel();
350
351 /**
352 Return translated label for businessAddressLabel field.
353 */
354 static QString businessAddressLabelLabel();
355
356 /**
357 Return translated label for homePhone field.
358 */
359 static QString homePhoneLabel();
360
361 /**
362 Return translated label for businessPhone field.
363 */
364 static QString businessPhoneLabel();
365
366 /**
367 Return translated label for mobilePhone field.
368 */
369 static QString mobilePhoneLabel();
370
371 /**
372 Return translated label for homeFax field.
373 */
374 static QString homeFaxLabel();
375
376 /**
377 Return translated label for businessFax field.
378 */
379 static QString businessFaxLabel();
380
381 /**
382 Return translated label for carPhone field.
383 */
384 static QString carPhoneLabel();
385
386 /**
387 Return translated label for isdn field.
388 */
389 static QString isdnLabel();
390
391 /**
392 Return translated label for pager field.
393 */
394 static QString pagerLabel();
395
396 /**
397 Return translated label for email field.
398 */
399 static QString emailLabel();
400
401 /**
402 Set mail client.
403 */
404 void setMailer( const QString &mailer );
405
406 /**
407 Return mail client.
408 */
409 QString mailer() const;
410
411 /**
412 Return translated label for mailer field.
413 */
414 static QString mailerLabel();
415
416 /**
417 Set time zone.
418 */
419 void setTimeZone( const TimeZone &timeZone );
420
421 /**
422 Return time zone.
423 */
424 TimeZone timeZone() const;
425
426 /**
427 Return translated label for timeZone field.
428 */
429 static QString timeZoneLabel();
430
431 /**
432 Set geographic position.
433 */
434 void setGeo( const Geo &geo );
435
436 /**
437 Return geographic position.
438 */
439 Geo geo() const;
440
441 /**
442 Return translated label for geo field.
443 */
444 static QString geoLabel();
445
446 /**
447 Set title.
448 */
449 void setTitle( const QString &title );
450
451 /**
452 Return title.
453 */
454 QString title() const;
455
456 /**
457 Return translated label for title field.
458 */
459 static QString titleLabel();
460
461 /**
462 Set role.
463 */
464 void setRole( const QString &role );
465
466 /**
467 Return role.
468 */
469 QString role() const;
470
471 /**
472 Return translated label for role field.
473 */
474 static QString roleLabel();
475
476 /**
477 Set organization.
478 */
479 void setOrganization( const QString &organization );
480
481 /**
482 Return organization.
483 */
484 QString organization() const;
485
486 /**
487 Return translated label for organization field.
488 */
489 static QString organizationLabel();
490
491 /**
492 Set department.
493 */
494 void setDepartment( const QString &department );
495
496 /**
497 Return department.
498 */
499 QString department() const;
500
501 /**
502 Return translated label for department field.
503 */
504 static QString departmentLabel();
505
506 /**
507 Set note.
508 */
509 void setNote( const QString &note );
510
511 /**
512 Return note.
513 */
514 QString note() const;
515
516 /**
517 Return translated label for note field.
518 */
519 static QString noteLabel();
520
521 /**
522 Set product identifier.
523 */
524 void setProductId( const QString &productId );
525
526 /**
527 Return product identifier.
528 */
529 QString productId() const;
530
531 /**
532 Return translated label for productId field.
533 */
534 static QString productIdLabel();
535
536 /**
537 Set revision date.
538 */
539 void setRevision( const QDateTime &revision );
540
541 /**
542 Return revision date.
543 */
544 QDateTime revision() const;
545
546 /**
547 Return translated label for revision field.
548 */
549 static QString revisionLabel();
550
551 /**
552 Set sort string.
553 */
554 void setSortString( const QString &sortString );
555
556 /**
557 Return sort string.
558 */
559 QString sortString() const;
560
561 /**
562 Return translated label for sortString field.
563 */
564 static QString sortStringLabel();
565
566 /**
567 Set homepage.
568 */
569 void setUrl( const KUrl &url );
570
571 /**
572 Return homepage.
573 */
574 KUrl url() const;
575
576 /**
577 Return translated label for url field.
578 */
579 static QString urlLabel();
580
581 /**
582 Set security class.
583 */
584 void setSecrecy( const Secrecy &secrecy );
585
586 /**
587 Return security class.
588 */
589 Secrecy secrecy() const;
590
591 /**
592 Return translated label for secrecy field.
593 */
594 static QString secrecyLabel();
595
596 /**
597 Set logo.
598 */
599 void setLogo( const Picture & );
600
601 /**
602 Return logo.
603 */
604 Picture logo() const;
605
606 /**
607 Return translated label for logo field.
608 */
609 static QString logoLabel();
610
611 /**
612 Set photo.
613 */
614 void setPhoto( const Picture &photo );
615
616 /**
617 Return photo.
618 */
619 Picture photo() const;
620
621 /**
622 Return translated label for photo field.
623 */
624 static QString photoLabel();
625
626 /**
627 Set sound.
628 */
629 void setSound( const Sound &sound );
630
631 /**
632 Return sound.
633 */
634 Sound sound() const;
635
636 /**
637 Return translated label for sound field.
638 */
639 static QString soundLabel();
640
641 /**
642 Set name fields by parsing the given string and trying to associate the
643 parts of the string with according fields. This function should probably
644 be a bit more clever.
645 */
646 void setNameFromString( const QString & );
647
648 /**
649 Return the name of the addressee. This is calculated from all the name
650 fields.
651 */
652 QString realName() const;
653
654 /**
655 Return the name that consists of all name parts.
656 */
657 QString assembledName() const;
658
659 /**
660 Return email address including real name.
661
662 @param email Email address to be used to construct the full email string.
663 If this is QString() the preferred email address is used.
664 */
665 QString fullEmail( const QString &email=QString() ) const;
666
667 /**
668 Insert an email address. If the email address already exists in this
669 addressee it is not duplicated.
670
671 @param email Email address
672 @param preferred Set to true, if this is the preferred email address of
673 the addressee.
674 */
675 void insertEmail( const QString &email, bool preferred=false );
676
677 /**
678 Remove email address. If the email address doesn't exist, nothing happens.
679
680 @param email Email address to remove
681 */
682 void removeEmail( const QString &email );
683
684 /**
685 Return preferred email address. This is the first email address or the
686 last one added with insertEmail() with a set preferred parameter.
687 */
688 QString preferredEmail() const;
689
690 /**
691 Return list of all email addresses.
692 */
693 QStringList emails() const;
694
695 /**
696 Set the emails to @p list.
697 The first email address gets the preferred one!
698 @param list The list of email addresses.
699 */
700 void setEmails( const QStringList& list);
701
702 /**
703 Insert a phone number. If a phone number with the same id already exists
704 in this addressee it is not duplicated.
705
706 @param phoneNumber The telephone number to insert to the addressee
707 */
708 void insertPhoneNumber( const PhoneNumber &phoneNumber );
709
710 /**
711 Remove phone number. If no phone number with the given id exists for this
712 addresse nothing happens.
713
714 @param phoneNumber The telephone number to remove from the addressee
715 */
716 void removePhoneNumber( const PhoneNumber &phoneNumber );
717
718 /**
719 Return phone number, which matches the given type.
720
721 @param type The type of phone number to get
722 */
723 PhoneNumber phoneNumber( PhoneNumber::Type type ) const;
724
725 /**
726 Return list of all phone numbers.
727 */
728 PhoneNumber::List phoneNumbers() const;
729
730 /**
731 Return list of phone numbers with a special type.
732
733 @param type The type of phone number to get
734 */
735 PhoneNumber::List phoneNumbers( PhoneNumber::Type type ) const;
736
737 /**
738 Return phone number with the given id.
739
740 @param id The identifier of the phone number to look for.
741 See PhoneNumber::id()
742 */
743 PhoneNumber findPhoneNumber( const QString &id ) const;
744
745 /**
746 Insert a key. If a key with the same id already exists
747 in this addressee it is not duplicated.
748
749 @param key The key to insert
750 */
751 void insertKey( const Key &key );
752
753 /**
754 Remove a key. If no key with the given id exists for this
755 addresse nothing happens.
756
757 @param key The key to remove
758 */
759 void removeKey( const Key &key );
760
761 /**
762 Return key, which matches the given type.
763 If @p type == Key::Custom you can specify a string
764 that should match. If you leave the string empty, the first
765 key with a custom value is returned.
766
767 @param type The type of key to look for
768 @param customTypeString A string to match custom keys against when
769 @p type is @c Key::Custom
770 */
771 Key key( Key::Type type, QString customTypeString = QString() ) const;
772
773 /**
774 Return list of all keys.
775 */
776 Key::List keys() const;
777
778 /**
779 Set the list of keys
780 @param keys The keys to be set.
781 */
782 void setKeys( const Key::List& keys);
783
784 /**
785 Return list of keys with a special type.
786 If @p type == Key::Custom you can specify a string
787 that should match. If you leave the string empty, all custom
788 keys will be returned.
789
790 @param type The type of key to look for
791 @param customTypeString A string to match custom keys against when
792 @p type is @c Key::Custom
793 */
794 Key::List keys( Key::Type type, QString customTypeString = QString() ) const;
795
796 /**
797 Return key with the given id.
798
799 @param id The identifier of the key to look for. See Key::id()
800 */
801 Key findKey( const QString &id ) const;
802
803 /**
804 Insert an address. If an address with the same id already exists
805 in this addressee it is not duplicated.
806
807 @param address The address to insert
808 */
809 void insertAddress( const Address &address );
810
811 /**
812 Remove address. If no address with the given id exists for this
813 addresse nothing happens.
814
815 @param address The address to remove
816 */
817 void removeAddress( const Address &address );
818
819 /**
820 Return address, which matches the given type.
821
822 @param type The type of address to look for
823 */
824 Address address( Address::Type type ) const;
825
826 /**
827 Return list of all addresses.
828 */
829 Address::List addresses() const;
830
831 /**
832 Return list of addresses with a special type.
833
834 @param type The type of addresses to look for
835 */
836 Address::List addresses( Address::Type type ) const;
837
838 /**
839 Return address with the given id.
840
841 @param id The identifier of the address to look for. See Address::id()
842 */
843 Address findAddress( const QString &id ) const;
844
845 /**
846 Insert category. If the category already exists it is not duplicated.
847 */
848 void insertCategory( const QString & );
849
850 /**
851 Remove category.
852 */
853 void removeCategory( const QString & );
854
855 /**
856 Return, if addressee has the given category.
857 */
858 bool hasCategory( const QString & ) const;
859
860 /**
861 Set categories to given value.
862 */
863 void setCategories( const QStringList & );
864
865 /**
866 Return list of all set categories.
867 */
868 QStringList categories() const;
869
870 /**
871 Insert custom entry. The entry is identified by the name of the inserting
872 application and a unique name. If an entry with the given app and name
873 already exists its value is replaced with the new given value.
874
875 An empty value isn't allowed (nothing happens if this is called with
876 any of the three arguments being empty)
877
878 @param app Name of the application inserting this custom entry
879 @param name Name of this application specific custom entry
880 @param value Value of this application specific custom entry
881 */
882 void insertCustom( const QString &app, const QString &name,
883 const QString &value );
884
885 /**
886 Remove custom entry.
887
888 @param app Name of the application which has inserted this custom entry
889 @param name Name of this application specific custom entry
890 */
891 void removeCustom( const QString &app, const QString &name );
892
893 /**
894 Return value of custom entry, identified by app and entry name.
895
896 @param app Name of the application which has inserted this custom entry
897 @param name Name of this application specific custom entry
898 */
899 QString custom( const QString &app, const QString &name ) const;
900
901 /**
902 Set all custom entries.
903 */
904 void setCustoms( const QStringList & );
905
906 /**
907 Return list of all custom entries.
908
909 The format of the custom entries is 'app-key:value' and the list is sorted
910 alphabetically by 'app-key'.
911 */
912 QStringList customs() const;
913
914 /**
915 Parse full email address. The result is given back in fullName and email.
916
917 @param rawEmail The input string to parse for name and email
918 @param fullName The name part of the @p rawEmail input, if it contained one
919 @param email The email part of the @p rawEmail input, if it contained one
920 */
921 static void parseEmailAddress( const QString &rawEmail, QString &fullName,
922 QString &email );
923
924 /**
925 Returns string representation of the addressee.
926 */
927 QString toString() const;
928
929#ifndef KDEPIM_NO_KRESOURCES
930 /**
931 Set resource where the addressee is from.
932
933 @param resource The Resource the addressee is from
934 */
935 void setResource( Resource *resource );
936
937 /**
938 Return pointer to resource.
939 */
940 Resource *resource() const;
941#endif
942
943 /**
944 Mark addressee as changed.
945
946 @param value Sets the status indicating changed data
947 */
948 void setChanged( bool value );
949
950 /**
951 Return whether the addressee is changed.
952 */
953 bool changed() const;
954
955 /**
956 Sets the sort mode implementation.
957
958 Comparing to addressee objects is delegated to an instance
959 of a subclass of KABC::SortMode.
960
961 @param mode The sort mode implementator to use
962 */
963 static void setSortMode( KABC::SortMode *mode );
964
965 /**
966 Return whether this addressee is "less-than" a given one
967
968 @param addr The addressee object to compare with
969
970 @see setSortMode()
971 */
972 bool operator< ( const Addressee &addr ) const;
973
974 /**
975 Returns the MIME type used for Addressees
976 */
977 static QString mimeType();
978
979 private:
980 class Private;
981 QSharedDataPointer<Private> d;
982};
983#ifdef kabc_EXPORTS
984KDE_DUMMY_QHASH_FUNCTION( Addressee )
985#endif
986
987KABC_EXPORT QDataStream &operator<<( QDataStream &, const Addressee & );
988KABC_EXPORT QDataStream &operator>>( QDataStream &, Addressee & );
989
990}
991
992#define KABC_ADDRESSEE_METATYPE_DEFINED 1
993Q_DECLARE_METATYPE( KABC::Addressee )
994
995#endif
996