1/*
2 This file is part of the KContacts framework.
3 SPDX-FileCopyrightText: 2001 Cornelius Schumacher <schumacher@kde.org>
4 SPDX-FileCopyrightText: 2013 Tobias Koenig <tokoe@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef KCONTACTS_ADDRESSEE_H
10#define KCONTACTS_ADDRESSEE_H
11
12#include <QDateTime>
13#include <QMap>
14#include <QSharedDataPointer>
15#include <QStringList>
16#include <QUrl>
17
18#include "address.h"
19#include "addresseelist.h"
20#include "calendarurl.h"
21#include "clientpidmap.h"
22#include "email.h"
23#include "fieldgroup.h"
24#include "gender.h"
25#include "geo.h"
26#include "impp.h"
27#include "key.h"
28#include "lang.h"
29#include "nickname.h"
30#include "org.h"
31#include "phonenumber.h"
32#include "picture.h"
33#include "related.h"
34#include "resourcelocatorurl.h"
35#include "role.h"
36#include "secrecy.h"
37#include "sound.h"
38#include "timezone.h"
39#include "title.h"
40
41namespace KContacts
42{
43
44/*!
45 * \qmlvaluetype addressee
46 * \inqmlmodule org.kde.contacts
47 * \nativetype KContacts::Addressee
48 * \brief Postal address information.
49 *
50 * \brief Address book entry.
51 *
52 * This class represents an entry in the address book.
53 */
54
55/*!
56 \class KContacts::Addressee
57 \inheaderfile KContacts/Addressee
58 \inmodule KContacts
59
60 \brief Address book entry.
61
62 This class represents an entry in the address book.
63
64 The data of this class is implicitly shared. You can pass this class by value.
65
66 If you need the name of a field for presenting it to the user you should use
67 the functions ending in Label(). They return a translated string which can be
68 used as label for the corresponding field.
69
70 About the name fields:
71
72 givenName() is the first name and familyName() the last name. In some
73 countries the family name comes first, that's the reason for the
74 naming. formattedName() is the full name with the correct formatting.
75 It is used as an override, when the correct formatting can't be generated
76 from the other name fields automatically.
77
78 realName() returns a fully formatted name(). It uses formattedName, if set,
79 otherwise it constructs the name from the name fields. As fallback, if
80 nothing else is set it uses name().
81
82 name() is the NAME type of RFC2426. It can be used as internal name for the
83 data entry, but shouldn't be used for displaying the data to the user.
84 */
85class KCONTACTS_EXPORT Addressee
86{
87 friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &, const Addressee &);
88 friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &, Addressee &);
89
90 Q_GADGET
91
92 /*!
93 * \qmlproperty bool addressee::isEmpty
94 */
95
96 /*!
97 * \property KContacts::Addressee::isEmpty
98 */
99 Q_PROPERTY(bool isEmpty READ isEmpty)
100
101 /*!
102 * \qmlproperty string addressee::uid
103 */
104
105 /*!
106 * \property KContacts::Addressee::uid
107 */
108 Q_PROPERTY(QString uid READ uid WRITE setUid)
109
110 /*!
111 * \qmlproperty string addressee::name
112 */
113
114 /*!
115 * \property KContacts::Addressee::name
116 */
117 Q_PROPERTY(QString name READ name WRITE setName)
118
119 /*!
120 * \qmlproperty string addressee::formattedName
121 */
122
123 /*!
124 * \property KContacts::Addressee::formattedName
125 */
126 Q_PROPERTY(QString formattedName READ formattedName WRITE setFormattedName)
127
128 /*!
129 * \qmlproperty string addressee::familyName
130 */
131
132 /*!
133 * \property KContacts::Addressee::familyName
134 */
135 Q_PROPERTY(QString familyName READ familyName WRITE setFamilyName)
136
137 /*!
138 * \qmlproperty string addressee::givenName
139 */
140
141 /*!
142 * \property KContacts::Addressee::givenName
143 */
144 Q_PROPERTY(QString givenName READ givenName WRITE setGivenName)
145
146 /*!
147 * \qmlproperty string addressee::additionalName
148 */
149
150 /*!
151 * \property KContacts::Addressee::additionalName
152 */
153 Q_PROPERTY(QString additionalName READ additionalName WRITE setAdditionalName)
154
155 /*!
156 * \qmlproperty string addressee::prefix
157 */
158
159 /*!
160 * \property KContacts::Addressee::prefix
161 */
162 Q_PROPERTY(QString prefix READ prefix WRITE setPrefix)
163
164 /*!
165 * \qmlproperty string addressee::suffix
166 */
167
168 /*!
169 * \property KContacts::Addressee::suffix
170 */
171 Q_PROPERTY(QString suffix READ suffix WRITE setSuffix)
172
173 /*!
174 * \qmlproperty string addressee::nickName
175 */
176
177 /*!
178 * \property KContacts::Addressee::nickName
179 */
180 Q_PROPERTY(QString nickName READ nickName)
181
182 /*!
183 * \qmlproperty date addressee::birthday
184 */
185
186 /*!
187 * \property KContacts::Addressee::birthday
188 */
189 Q_PROPERTY(QDateTime birthday READ birthday WRITE setBirthdayProperty) // special write method due to withTime argument
190
191 /*!
192 * \qmlproperty string addressee::birthdayHasTime
193 */
194
195 /*!
196 * \property KContacts::Addressee::birthdayHasTime
197 */
198 Q_PROPERTY(bool birthdayHasTime READ birthdayHasTime)
199
200 /*!
201 * \qmlproperty string addressee::mailer
202 */
203
204 /*!
205 * \property KContacts::Addressee::mailer
206 */
207 Q_PROPERTY(QString mailer READ mailer WRITE setMailer)
208
209 /*!
210 * \qmlproperty geo addressee::geo
211 */
212
213 /*!
214 * \property KContacts::Addressee::geo
215 */
216 Q_PROPERTY(KContacts::Geo geo READ geo WRITE setGeo)
217
218 /*!
219 * \qmlproperty string addressee::title
220 */
221
222 /*!
223 * \property KContacts::Addressee::title
224 */
225 Q_PROPERTY(QString title READ title)
226
227 /*!
228 * \qmlproperty string addressee::role
229 */
230
231 /*!
232 * \property KContacts::Addressee::role
233 */
234 Q_PROPERTY(QString role READ role)
235
236 /*!
237 * \qmlproperty string addressee::organization
238 */
239
240 /*!
241 * \property KContacts::Addressee::organization
242 */
243 Q_PROPERTY(QString organization READ organization)
244
245 /*!
246 * \qmlproperty string addressee::department
247 */
248
249 /*!
250 * \property KContacts::Addressee::department
251 */
252 Q_PROPERTY(QString department READ department WRITE setDepartment)
253
254 /*!
255 * \qmlproperty string addressee::note
256 */
257
258 /*!
259 * \property KContacts::Addressee::note
260 */
261 Q_PROPERTY(QString note READ note WRITE setNote)
262
263 /*!
264 * \qmlproperty string addressee::productId
265 */
266
267 /*!
268 * \property KContacts::Addressee::productId
269 */
270 Q_PROPERTY(QString productId READ productId WRITE setProductId)
271
272 /*!
273 * \qmlproperty date addressee::revision
274 */
275
276 /*!
277 * \property KContacts::Addressee::revision
278 */
279 Q_PROPERTY(QDateTime revision READ revision)
280
281 /*!
282 * \qmlproperty string addressee::sortString
283 */
284
285 /*!
286 * \property KContacts::Addressee::sortString
287 */
288 Q_PROPERTY(QString sortString READ sortString WRITE setSortString)
289
290 /*!
291 * \qmlproperty string addressee::url
292 */
293
294 /*!
295 * \property KContacts::Addressee::url
296 */
297 Q_PROPERTY(KContacts::ResourceLocatorUrl url READ url WRITE setUrl)
298
299 /*!
300 * \qmlproperty list<resourceLocatorUrl> addressee::extraUrls
301 */
302
303 /*!
304 * \property KContacts::Addressee::extraUrls
305 */
306 Q_PROPERTY(QList<KContacts::ResourceLocatorUrl> extraUrls READ extraUrlList WRITE setExtraUrlList)
307
308 /*!
309 * \qmlproperty string addressee::realName
310 */
311
312 /*!
313 * \property KContacts::Addressee::realName
314 */
315 Q_PROPERTY(QString realName READ realName)
316
317 /*!
318 * \qmlproperty string addressee::assembledName
319 */
320
321 /*!
322 * \property KContacts::Addressee::assembledName
323 */
324 Q_PROPERTY(QString assembledName READ assembledName)
325
326 /*!
327 * \qmlproperty string addressee::preferredEmail
328 */
329
330 /*!
331 * \property KContacts::Addressee::preferredEmail
332 */
333 Q_PROPERTY(QString preferredEmail READ preferredEmail)
334
335 /*!
336 * \qmlproperty list<email> addressee::emails
337 */
338
339 /*!
340 * \property KContacts::Addressee::emails
341 */
342 Q_PROPERTY(QList<KContacts::Email> emails READ emailList WRITE setEmailList)
343
344 /*!
345 * \qmlproperty list<phoneNumber> addressee::phoneNumbers
346 */
347
348 /*!
349 * \property KContacts::Addressee::phoneNumbers
350 */
351 Q_PROPERTY(QList<KContacts::PhoneNumber> phoneNumbers READ phoneNumbers WRITE setPhoneNumbers)
352
353 /*!
354 * \qmlproperty list<address> addressee::addresses
355 */
356
357 /*!
358 * \property KContacts::Addressee::addresses
359 */
360 Q_PROPERTY(QList<KContacts::Address> addresses READ addresses WRITE setAddresses)
361
362 /*!
363 * \qmlproperty list<string> addressee::categories
364 */
365
366 /*!
367 * \property KContacts::Addressee::categories
368 */
369 Q_PROPERTY(QStringList categories READ categories WRITE setCategories)
370
371 /*!
372 * \qmlproperty list<string> addressee::customs
373 */
374
375 /*!
376 * \property KContacts::Addressee::customs
377 */
378 Q_PROPERTY(QStringList customs READ customs)
379
380 /*!
381 * \qmlproperty bool addressee::changed
382 */
383
384 /*!
385 * \property KContacts::Addressee::changed
386 */
387 Q_PROPERTY(bool changed READ changed WRITE setChanged)
388
389 /*!
390 * \qmlproperty list<impp> addressee::impps
391 */
392
393 /*!
394 * \property KContacts::Addressee::impps
395 */
396 Q_PROPERTY(QList<KContacts::Impp> impps READ imppList WRITE setImppList)
397
398 /*!
399 * \qmlproperty date addressee::anniversary
400 */
401
402 /*!
403 * \property KContacts::Addressee::anniversary
404 */
405 Q_PROPERTY(QDate anniversary READ anniversary WRITE setAnniversary)
406
407 /*!
408 * \qmlproperty string addressee::assistantsName
409 */
410
411 /*!
412 * \property KContacts::Addressee::assistantsName
413 */
414 Q_PROPERTY(QString assistantsName READ assistantsName WRITE setAssistantsName)
415
416 /*!
417 * \qmlproperty url addressee::blogFeed
418 */
419
420 /*!
421 * \property KContacts::Addressee::blogFeed
422 */
423 Q_PROPERTY(QUrl blogFeed READ blogFeed WRITE setBlogFeed)
424
425 /*!
426 * \qmlproperty string addressee::managersName
427 */
428
429 /*!
430 * \property KContacts::Addressee::managersName
431 */
432 Q_PROPERTY(QString managersName READ managersName WRITE setManagersName)
433
434 /*!
435 * \qmlproperty string addressee::office
436 */
437
438 /*!
439 * \property KContacts::Addressee::office
440 */
441 Q_PROPERTY(QString office READ office WRITE setOffice)
442
443 /*!
444 * \qmlproperty string addressee::profession
445 */
446
447 /*!
448 * \property KContacts::Addressee::profession
449 */
450 Q_PROPERTY(QString profession READ profession WRITE setProfession)
451
452 /*!
453 * \qmlproperty string addressee::spousesName
454 */
455
456 /*!
457 * \property KContacts::Addressee::spousesName
458 */
459 Q_PROPERTY(QString spousesName READ spousesName WRITE setSpousesName)
460
461 /*!
462 * \qmlproperty picture addressee::photo
463 */
464
465 /*!
466 * \property KContacts::Addressee::photo
467 */
468 Q_PROPERTY(KContacts::Picture photo READ photo WRITE setPhoto)
469
470 // ### the following properties are still missing:
471 // - logos, photos, sounds
472 // - keys
473 // - the list variants for nicks, titles, roles, orgs
474 // - timezone, secrecy, gender, kind, members, relationships, language
475 // - field groups, sourceUrls, calendarUrls
476
477public:
478 /*!
479 A list of addressee objects
480 */
481 typedef AddresseeList List;
482
483 /*!
484 Construct an empty address book entry.
485 */
486 Addressee();
487
488 /*!
489 Destroys the address book entry.
490 */
491 ~Addressee();
492
493 /*!
494 Copy constructor.
495 */
496 Addressee(const Addressee &other);
497
498 /*!
499 Assignment operator.
500
501 Returns a reference to \c this
502 */
503 Addressee &operator=(const Addressee &other);
504
505 /*!
506 Equality operator.
507
508 Returns \c true if \c this and the given addressee are equal,
509 otherwise \c false
510 */
511 bool operator==(const Addressee &other) const;
512
513 /*!
514 Not-equal operator.
515
516 Returns \c true if \c this and the given addressee are not equal,
517 otherwise \c false
518 */
519 bool operator!=(const Addressee &other) const;
520
521 /*!
522 Return if the address book entry is empty.
523 */
524 bool isEmpty() const;
525
526 /*!
527 Set unique identifier.
528
529 \a uid the KABC unique identifier
530 */
531 void setUid(const QString &uid);
532
533 /*!
534 Return unique identifier.
535 */
536 QString uid() const;
537
538 /*!
539 Return translated label for uid field.
540 */
541 static QString uidLabel();
542
543 /*!
544 Set name.
545 */
546 void setName(const QString &name);
547
548 /*!
549 Return name.
550 */
551 QString name() const;
552
553 /*!
554 Return translated label for name field.
555 */
556 static QString nameLabel();
557
558 /*!
559 Set formatted name.
560 */
561 void setFormattedName(const QString &formattedName);
562
563 /*!
564 Return formatted name.
565 */
566 QString formattedName() const;
567
568 /*!
569 Return translated label for formattedName field.
570 */
571 static QString formattedNameLabel();
572
573 /*!
574 Set family name.
575 */
576 void setFamilyName(const QString &familyName);
577
578 /*!
579 Return family name.
580 */
581 QString familyName() const;
582
583 /*!
584 Return translated label for familyName field.
585 */
586 static QString familyNameLabel();
587
588 /*!
589 Set given name.
590 */
591 void setGivenName(const QString &givenName);
592
593 /*!
594 Return given name.
595 */
596 QString givenName() const;
597
598 /*!
599 Return translated label for givenName field.
600 */
601 static QString givenNameLabel();
602
603 /*!
604 Set additional names.
605 */
606 void setAdditionalName(const QString &additionalName);
607
608 /*!
609 Return additional names.
610 */
611 QString additionalName() const;
612
613 /*!
614 Return translated label for additionalName field.
615 */
616 static QString additionalNameLabel();
617
618 /*!
619 Set honorific prefixes.
620 */
621 void setPrefix(const QString &prefix);
622
623 /*!
624 Return honorific prefixes.
625 */
626 QString prefix() const;
627
628 /*!
629 Return translated label for prefix field.
630 */
631 static QString prefixLabel();
632
633 /*!
634 Set honorific suffixes.
635 */
636 void setSuffix(const QString &suffix);
637
638 /*!
639 Return honorific suffixes.
640 */
641 QString suffix() const;
642
643 /*!
644 Return translated label for suffix field.
645 */
646 static QString suffixLabel();
647
648 /*!
649 Set nick name.
650 */
651 void setNickName(const QString &nickName);
652
653 /*!
654 */
655 void setNickName(const NickName &nickName);
656
657 /*!
658 */
659 void insertExtraNickName(const NickName &nickName);
660
661 /*!
662 */
663 void setExtraNickNameList(const NickName::List &nickNameList);
664
665 /*!
666 */
667 NickName::List extraNickNameList() const;
668
669 /*!
670 Return nick name.
671 */
672 QString nickName() const;
673
674 /*!
675 Return translated label for nickName field.
676 */
677 static QString nickNameLabel();
678
679 /*!
680 Set birthday (date and time). If withTime is false the time will be set
681 to midnight and birthdayHasTime() will return false afterwards.
682 \since 5.4
683 */
684 void setBirthday(const QDateTime &birthday, bool withTime = true);
685
686 /*!
687 Set birthday (date only). birthdayHasTime() will return false afterwards.
688 */
689 void setBirthday(const QDate &birthday);
690
691 /*!
692 Return birthday. (If a valid date has been set, birthday().time() will
693 always return a valid QTime!)
694 */
695 QDateTime birthday() const;
696
697 /*!
698 Returns true if birthday has been set with a time. Returns false otherwise.
699 */
700 bool birthdayHasTime() const;
701
702 /*!
703 Return translated label for birthday field.
704 */
705 static QString birthdayLabel();
706
707 /*!
708 Return translated label for homeAddressStreet field.
709 */
710 static QString homeAddressStreetLabel();
711
712 /*!
713 Return translated label for homeAddressPostOfficeBox field.
714 */
715 static QString homeAddressPostOfficeBoxLabel();
716
717 /*!
718 Return translated label for homeAddressLocality field.
719 */
720 static QString homeAddressLocalityLabel();
721
722 /*!
723 Return translated label for homeAddressRegion field.
724 */
725 static QString homeAddressRegionLabel();
726
727 /*!
728 Return translated label for homeAddressPostalCode field.
729 */
730 static QString homeAddressPostalCodeLabel();
731
732 /*!
733 Return translated label for homeAddressCountry field.
734 */
735 static QString homeAddressCountryLabel();
736
737 /*!
738 Return translated label for homeAddressLabel field.
739 */
740 static QString homeAddressLabelLabel();
741
742 /*!
743 Return translated label for businessAddressStreet field.
744 */
745 static QString businessAddressStreetLabel();
746
747 /*!
748 Return translated label for businessAddressPostOfficeBox field.
749 */
750 static QString businessAddressPostOfficeBoxLabel();
751
752 /*!
753 Return translated label for businessAddressLocality field.
754 */
755 static QString businessAddressLocalityLabel();
756
757 /*!
758 Return translated label for businessAddressRegion field.
759 */
760 static QString businessAddressRegionLabel();
761
762 /*!
763 Return translated label for businessAddressPostalCode field.
764 */
765 static QString businessAddressPostalCodeLabel();
766
767 /*!
768 Return translated label for businessAddressCountry field.
769 */
770 static QString businessAddressCountryLabel();
771
772 /*!
773 Return translated label for businessAddressLabel field.
774 */
775 static QString businessAddressLabelLabel();
776
777 /*!
778 Return translated label for homePhone field.
779 */
780 static QString homePhoneLabel();
781
782 /*!
783 Return translated label for businessPhone field.
784 */
785 static QString businessPhoneLabel();
786
787 /*!
788 Return translated label for mobilePhone field.
789 */
790 static QString mobilePhoneLabel();
791
792 /*!
793 Return translated label for homeFax field.
794 */
795 static QString homeFaxLabel();
796
797 /*!
798 Return translated label for businessFax field.
799 */
800 static QString businessFaxLabel();
801
802 /*!
803 Return translated label for carPhone field.
804 */
805 static QString carPhoneLabel();
806
807 /*!
808 Return translated label for isdn field.
809 */
810 static QString isdnLabel();
811
812 /*!
813 Return translated label for pager field.
814 */
815 static QString pagerLabel();
816
817 /*!
818 Return translated label for email field.
819 */
820 static QString emailLabel();
821
822 /*!
823 Set mail client.
824 */
825 void setMailer(const QString &mailer);
826
827 /*!
828 Return mail client.
829 */
830 QString mailer() const;
831
832 /*!
833 Return translated label for mailer field.
834 */
835 static QString mailerLabel();
836
837 /*!
838 Set time zone.
839 */
840 void setTimeZone(const TimeZone &timeZone);
841
842 /*!
843 Return time zone.
844 */
845 TimeZone timeZone() const;
846
847 /*!
848 Return translated label for timeZone field.
849 */
850 static QString timeZoneLabel();
851
852 /*!
853 Set geographic position.
854 */
855 void setGeo(const Geo &geo);
856
857 /*!
858 Return geographic position.
859 */
860 Geo geo() const;
861
862 /*!
863 Return translated label for geo field.
864 */
865 static QString geoLabel();
866
867 // Remove in kf6
868 /*!
869 Set title.
870 */
871 void setTitle(const QString &title);
872
873 /*!
874 */
875 void setTitle(const Title &title);
876
877 /*!
878 */
879 void insertExtraTitle(const Title &title);
880
881 /*!
882 */
883 void setExtraTitleList(const Title::List &urltitle);
884
885 /*!
886 */
887 Title::List extraTitleList() const;
888
889 /*!
890 Return title.
891 */
892 QString title() const;
893
894 /*!
895 Return translated label for title field.
896 */
897 static QString titleLabel();
898
899 /*!
900 Set role.
901 */
902 void setRole(const QString &role);
903
904 /*!
905 */
906 void setRole(const Role &role);
907
908 /*!
909 */
910 void insertExtraRole(const Role &role);
911
912 /*!
913 */
914 void setExtraRoleList(const Role::List &roleList);
915
916 /*!
917 */
918 Role::List extraRoleList() const;
919
920 /*!
921 Return role.
922 */
923 QString role() const;
924
925 /*!
926 Return translated label for role field.
927 */
928 static QString roleLabel();
929
930 // Remove in kf6
931 /*!
932 Set organization.
933 */
934 void setOrganization(const QString &organization);
935
936 /*!
937 */
938 void setOrganization(const Org &organization);
939
940 /*!
941 */
942 void insertExtraOrganization(const Org &organization);
943
944 /*!
945 */
946 void setExtraOrganizationList(const Org::List &orgList);
947
948 /*!
949 */
950 Org::List extraOrganizationList() const;
951
952 /*!
953 Return organization.
954 */
955 QString organization() const;
956
957 /*!
958 Return translated label for organization field.
959 */
960 static QString organizationLabel();
961
962 /*!
963 Set department.
964 */
965 void setDepartment(const QString &department);
966
967 /*!
968 Return department.
969 */
970 QString department() const;
971
972 /*!
973 Return translated label for department field.
974 */
975 static QString departmentLabel();
976
977 /*!
978 Set note.
979 */
980 void setNote(const QString &note);
981
982 /*!
983 Return note.
984 */
985 QString note() const;
986
987 /*!
988 Return translated label for note field.
989 */
990 static QString noteLabel();
991
992 /*!
993 Set product identifier.
994 */
995 void setProductId(const QString &productId);
996
997 /*!
998 Return product identifier.
999 */
1000 QString productId() const;
1001
1002 /*!
1003 Return translated label for productId field.
1004 */
1005 static QString productIdLabel();
1006
1007 /*!
1008 Set revision date.
1009 */
1010 void setRevision(const QDateTime &revision);
1011
1012 /*!
1013 Return revision date.
1014 */
1015 QDateTime revision() const;
1016
1017 /*!
1018 Return translated label for revision field.
1019 */
1020 static QString revisionLabel();
1021
1022 /*!
1023 Set sort string.
1024 */
1025 void setSortString(const QString &sortString);
1026
1027 /*!
1028 Return sort string.
1029 */
1030 QString sortString() const;
1031
1032 /*!
1033 Return translated label for sortString field.
1034 */
1035 static QString sortStringLabel();
1036
1037 /*!
1038 Set homepage.
1039 */
1040 void setUrl(const ResourceLocatorUrl &url);
1041 // kf6: remove it
1042 void setUrl(const QUrl &url);
1043
1044 /*!
1045 Return homepage.
1046 */
1047 ResourceLocatorUrl url() const;
1048
1049 /*!
1050 Return translated label for url field.
1051 */
1052 static QString urlLabel();
1053
1054 /*!
1055 Set security class.
1056 */
1057 void setSecrecy(const Secrecy &secrecy);
1058
1059 /*!
1060 Return security class.
1061 */
1062 Secrecy secrecy() const;
1063
1064 /*!
1065 Return translated label for secrecy field.
1066 */
1067 static QString secrecyLabel();
1068
1069 /*!
1070 Set logo.
1071 */
1072 void setLogo(const Picture &);
1073
1074 /*!
1075 Return logo.
1076 */
1077 Picture logo() const;
1078
1079 /*!
1080 Return translated label for logo field.
1081 */
1082 static QString logoLabel();
1083
1084 /*!
1085 Set photo.
1086 */
1087 void setPhoto(const Picture &photo);
1088
1089 /*!
1090 Return photo.
1091 */
1092 Picture photo() const;
1093
1094 /*!
1095 Return translated label for photo field.
1096 */
1097 static QString photoLabel();
1098
1099 /*!
1100 Set sound.
1101 */
1102 void setSound(const Sound &sound);
1103
1104 /*!
1105 Return sound.
1106 */
1107 Sound sound() const;
1108
1109 /*!
1110 Return translated label for sound field.
1111 */
1112 static QString soundLabel();
1113
1114 /*!
1115 Set name fields by parsing the given string and trying to associate the
1116 parts of the string with according fields. This function should probably
1117 be a bit more clever.
1118 */
1119 void setNameFromString(const QString &s);
1120
1121 /*!
1122 Return the name of the addressee. This is calculated from all the name
1123 fields.
1124 */
1125 QString realName() const;
1126
1127 /*!
1128 Return the name that consists of all name parts.
1129 */
1130 QString assembledName() const;
1131
1132 /*!
1133 Return email address including real name.
1134
1135 \a email Email address to be used to construct the full email string.
1136 If this is QString() the preferred email address is used.
1137 */
1138 QString fullEmail(const QString &email = QString()) const;
1139
1140 /*!
1141 Adds an email address. If the email address (i.e. email.mail()) already
1142 exists in this addressee it won't be duplicated, instead email is assigned
1143 to it.
1144
1145 \since 5.88
1146 */
1147 void addEmail(const Email &email);
1148
1149 /*!
1150 Remove email address. If the email address doesn't exist, nothing happens.
1151
1152 \a email Email address to remove
1153 */
1154 void removeEmail(const QString &email);
1155
1156 /*!
1157 Return preferred email address. This is the first email address or the last
1158 one added with insertEmail() or addEmail() with a set preferred parameter.
1159 */
1160 QString preferredEmail() const;
1161
1162 /*!
1163 Return list of all email addresses.
1164 */
1165 QStringList emails() const;
1166
1167 /*!
1168 Set the emails to \a list.
1169 The first email address gets the preferred one!
1170 */
1171 void setEmails(const QStringList &list);
1172
1173 /*!
1174 Insert a phone number. If a phone number with the same id already exists
1175 in this addressee it is not duplicated.
1176
1177 \a phoneNumber The telephone number to insert to the addressee
1178 */
1179 void insertPhoneNumber(const PhoneNumber &phoneNumber);
1180
1181 /*!
1182 Remove phone number. If no phone number with the given id exists for this
1183 addressee, nothing happens.
1184
1185 \a phoneNumber The telephone number to remove from the addressee
1186 */
1187 void removePhoneNumber(const PhoneNumber &phoneNumber);
1188
1189 /*!
1190 Return phone number, which matches the given type.
1191
1192 \a type The type of phone number to get
1193 */
1194 PhoneNumber phoneNumber(PhoneNumber::Type type) const;
1195
1196 /*!
1197 Return list of all phone numbers.
1198 */
1199 PhoneNumber::List phoneNumbers() const;
1200
1201 void setPhoneNumbers(const PhoneNumber::List &phoneNumbers);
1202
1203 /*!
1204 Return list of phone numbers with a special type.
1205
1206 \a type The type of phone number to get
1207 */
1208 PhoneNumber::List phoneNumbers(PhoneNumber::Type type) const;
1209
1210 /*!
1211 Return phone number with the given id.
1212
1213 \a id The identifier of the phone number to look for.
1214 See PhoneNumber::id()
1215 */
1216 PhoneNumber findPhoneNumber(const QString &id) const;
1217
1218 /*!
1219 Insert a key. If a key with the same id already exists
1220 in this addressee it is not duplicated.
1221
1222 \a key The key to insert
1223 */
1224 void insertKey(const Key &key);
1225
1226 /*!
1227 Remove a key. If no key with the given id exists for this
1228 addressee, nothing happens.
1229
1230 \a key The key to remove
1231 */
1232 void removeKey(const Key &key);
1233
1234 /*!
1235 Return key, which matches the given type.
1236 If \a type == Key::Custom you can specify a string
1237 that should match. If you leave the string empty, the first
1238 key with a custom value is returned.
1239
1240 \a type The type of key to look for
1241
1242 \a customTypeString A string to match custom keys against when
1243 \a type is \c Key::Custom
1244 */
1245 Key key(Key::Type type, const QString &customTypeString = QString()) const;
1246
1247 /*!
1248 Return list of all keys.
1249 */
1250 Key::List keys() const;
1251
1252 /*!
1253 Set the list of keys
1254 \a keys The keys to be set.
1255 */
1256 void setKeys(const Key::List &keys);
1257
1258 /*!
1259 Return list of keys with a special type.
1260 If \a type == Key::Custom you can specify a string
1261 that should match. If you leave the string empty, all custom
1262 keys will be returned.
1263
1264 \a type The type of key to look for
1265
1266 \a customTypeString A string to match custom keys against when
1267 \a type is \c Key::Custom
1268 */
1269 Key::List keys(Key::Type type, const QString &customTypeString = QString()) const;
1270
1271 /*!
1272 Return key with the given id.
1273
1274 \a id The identifier of the key to look for. See Key::id()
1275 */
1276 Key findKey(const QString &id) const;
1277
1278 /*!
1279 Insert an address. If an address with the same id already exists
1280 in this addressee it is not duplicated.
1281
1282 \a address The address to insert
1283 */
1284 void insertAddress(const Address &address);
1285
1286 /*!
1287 Remove address. If no address with the given id exists for this
1288 addressee, nothing happens.
1289
1290 \a address The address to remove
1291 */
1292 void removeAddress(const Address &address);
1293
1294 /*!
1295 Set the addressee
1296
1297 \a addresses The new addresses
1298 \since 5.100
1299 */
1300 void setAddresses(const Address::List &addresses);
1301
1302 /*!
1303 Return address, which matches the given type.
1304
1305 \a type The type of address to look for
1306 */
1307 Address address(Address::Type type) const;
1308
1309 /*!
1310 Return list of all addresses.
1311 */
1312 Address::List addresses() const;
1313
1314 /*!
1315 Return list of addresses with a special type.
1316
1317 \a type The type of addresses to look for
1318 */
1319 Address::List addresses(Address::Type type) const;
1320
1321 /*!
1322 Return address with the given id.
1323
1324 \a id The identifier of the address to look for. See Address::id()
1325 */
1326 Address findAddress(const QString &id) const;
1327
1328 /*!
1329 Insert category. If the category already exists it is not duplicated.
1330 */
1331 void insertCategory(const QString &category);
1332
1333 /*!
1334 Remove category.
1335 */
1336 void removeCategory(const QString &category);
1337
1338 /*!
1339 Return, if addressee has the given category.
1340 */
1341 bool hasCategory(const QString &category) const;
1342
1343 /*!
1344 Set categories to given value.
1345 */
1346 void setCategories(const QStringList &category);
1347
1348 /*!
1349 Return list of all set categories.
1350 */
1351 QStringList categories() const;
1352
1353 /*!
1354 Insert custom entry. The entry is identified by the name of the inserting
1355 application and a unique name. If an entry with the given app and name
1356 already exists its value is replaced with the new given value.
1357
1358 An empty value isn't allowed (nothing happens if this is called with
1359 any of the three arguments being empty)
1360
1361 \a app Name of the application inserting this custom entry
1362
1363 \a name Name of this application specific custom entry
1364
1365 \a value Value of this application specific custom entry
1366 */
1367 void insertCustom(const QString &app, const QString &name, const QString &value);
1368
1369 /*!
1370 Remove custom entry.
1371
1372 \a app Name of the application which has inserted this custom entry
1373
1374 \a name Name of this application specific custom entry
1375 */
1376 void removeCustom(const QString &app, const QString &name);
1377
1378 /*!
1379 Return value of custom entry, identified by app and entry name.
1380
1381 \a app Name of the application which has inserted this custom entry
1382
1383 \a name Name of this application specific custom entry
1384 */
1385 QString custom(const QString &app, const QString &name) const;
1386
1387 /*!
1388 Set all custom entries.
1389 */
1390 void setCustoms(const QStringList &customs);
1391
1392 /*!
1393 Return list of all custom entries.
1394
1395 The format of the custom entries is 'app-key:value' and the list is sorted
1396 alphabetically by 'app-key'.
1397 */
1398 QStringList customs() const;
1399
1400 /*!
1401 Parse full email address. The result is given back in fullName and email.
1402
1403 \a rawEmail The input string to parse for name and email
1404
1405 \a fullName The name part of the \a rawEmail input, if it contained one
1406
1407 \a email The email part of the \a rawEmail input, if it contained one
1408 */
1409 static void parseEmailAddress(const QString &rawEmail, QString &fullName, QString &email);
1410
1411 /*!
1412 Returns string representation of the addressee.
1413 */
1414 QString toString() const;
1415
1416 /*!
1417 Mark addressee as changed.
1418
1419 \a value Sets the status indicating changed data
1420 */
1421 void setChanged(bool value);
1422
1423 /*!
1424 Return whether the addressee is changed.
1425 */
1426 bool changed() const;
1427
1428 /*!
1429 Returns the MIME type used for Addressees
1430 */
1431 static QString mimeType();
1432
1433 KContacts::Email::List emailList() const;
1434 void setEmailList(const Email::List &list);
1435
1436 /*!
1437 * Remove Language
1438 */
1439 void removeLang(const QString &language);
1440 /*!
1441 * Insert Language
1442 */
1443 void insertLang(const Lang &language);
1444 /*!
1445 * Returns List of lang
1446 */
1447 Lang::List langs() const;
1448 /*!
1449 */
1450 void setLangs(const Lang::List &langs);
1451
1452 /*!
1453 */
1454 void setGender(const Gender &gender);
1455
1456 /*!
1457 */
1458 Gender gender() const;
1459
1460 /*!
1461 */
1462 QString kind() const;
1463
1464 /*!
1465 */
1466 void setKind(const QString &kind);
1467
1468 /*!
1469 */
1470 void insertCalendarUrl(const CalendarUrl &calendarUrl);
1471
1472 /*!
1473 */
1474 CalendarUrl::List calendarUrlList() const;
1475
1476 /*!
1477 */
1478 void insertExtraSound(const Sound &sound);
1479
1480 /*!
1481 */
1482 void setExtraSoundList(const Sound::List &soundList);
1483
1484 /*!
1485 */
1486 Sound::List extraSoundList() const;
1487
1488 /*!
1489 */
1490 void insertExtraPhoto(const Picture &picture);
1491
1492 /*!
1493 */
1494 void setExtraPhotoList(const Picture::List &pictureList);
1495
1496 /*!
1497 */
1498 Picture::List extraPhotoList() const;
1499
1500 /*!
1501 */
1502 void insertExtraLogo(const Picture &);
1503
1504 /*!
1505 */
1506 void setExtraLogoList(const Picture::List &logoList);
1507
1508 /*!
1509 */
1510 Picture::List extraLogoList() const;
1511
1512 /*!
1513 */
1514 ResourceLocatorUrl::List extraUrlList() const;
1515
1516 /*!
1517 */
1518 void setExtraUrlList(const ResourceLocatorUrl::List &urlList);
1519
1520 /*!
1521 */
1522 void insertExtraUrl(const ResourceLocatorUrl &url);
1523
1524 // Member
1525 /*!
1526 */
1527 void insertMember(const QString &member);
1528
1529 /*!
1530 */
1531 void setMembers(const QStringList &c);
1532
1533 /*!
1534 */
1535 QStringList members() const;
1536
1537 // Relation
1538 /*!
1539 */
1540 void insertRelationship(const Related &related);
1541
1542 /*!
1543 */
1544 void setRelationships(const Related::List &c);
1545
1546 /*!
1547 */
1548 Related::List relationships() const;
1549
1550 // Source
1551 /*!
1552 */
1553 void insertSourceUrl(const QUrl &url);
1554
1555 /*!
1556 */
1557 void setSourcesUrlList(const QList<QUrl> &urlList);
1558
1559 /*!
1560 */
1561 QList<QUrl> sourcesUrlList() const;
1562
1563 // Impp
1564 /*!
1565 */
1566 Impp::List imppList() const;
1567
1568 /*!
1569 */
1570 void setImppList(const Impp::List &imppList);
1571
1572 /*!
1573 */
1574 void insertImpp(const Impp &impp);
1575
1576 // FieldGroup
1577 /*!
1578 */
1579 FieldGroup::List fieldGroupList() const;
1580
1581 /*!
1582 */
1583 void setFieldGroupList(const FieldGroup::List &fieldGroupList);
1584
1585 /*!
1586 */
1587 void insertFieldGroup(const FieldGroup &fieldGroup);
1588
1589 // ClientPidMap
1590 /*!
1591 */
1592 ClientPidMap::List clientPidMapList() const;
1593
1594 /*!
1595 */
1596 void setClientPidMapList(const ClientPidMap::List &clientpidmaplist);
1597
1598 /*!
1599 */
1600 void insertClientPidMap(const ClientPidMap &clientpidmap);
1601
1602 /*!
1603 * Returns the contact's anniversary date.
1604 *
1605 * \note This is a non-standard extension using the \c X-Anniversary field.
1606 *
1607 * \since 5.12
1608 */
1609 QDate anniversary() const;
1610 /*!
1611 * Sets the contact's anniversary date.
1612 *
1613 * \note This is a non-standard extension using the \c X-Anniversary field.
1614 *
1615 * \since 5.12
1616 */
1617 void setAnniversary(const QDate &anniversary);
1618
1619 /*!
1620 * Returns the contact's assistant's name.
1621 *
1622 * \note This is a non-standard extension using the \c X-AssistantsName field.
1623 *
1624 * \since 5.12
1625 */
1626 QString assistantsName() const;
1627 /*!
1628 * Set the contact's assistant's name.
1629 *
1630 * \note This is a non-standard extension using the \c X-AssistantsName field.
1631 *
1632 * \since 5.12
1633 */
1634 void setAssistantsName(const QString &assistantsName);
1635
1636 /*!
1637 * Returns the contact's blog feed.
1638 *
1639 * \note This is a non-standard extension using the \c BlogFeed field.
1640 *
1641 * \since 5.12
1642 */
1643 QUrl blogFeed() const;
1644 /*!
1645 * Set the contact's blog feed.
1646 *
1647 * \note This is a non-standard extension using the \c BlogFeed field.
1648 *
1649 * \since 5.12
1650 */
1651 void setBlogFeed(const QUrl &blogFeed);
1652
1653 /*!
1654 * Returns the contact's manager's name.
1655 *
1656 * \note This is a non-standard extension using the \c X-ManagersName field.
1657 *
1658 * \since 5.12
1659 */
1660 QString managersName() const;
1661 /*!
1662 * Set the contact's manager's name.
1663 *
1664 * \note This is a non-standard extension using the \c X-ManagersName field.
1665 *
1666 * \since 5.12
1667 */
1668 void setManagersName(const QString &managersName);
1669
1670 /*!
1671 * Returns the contact's office.
1672 *
1673 * \note This is a non-standard extension using the \c X-Office field.
1674 *
1675 * \since 5.12
1676 */
1677 QString office() const;
1678 /*!
1679 * Set the contact's office.
1680 *
1681 * \note This is a non-standard extension using the \c X-Office field.
1682 *
1683 * \since 5.12
1684 */
1685 void setOffice(const QString &office);
1686
1687 /*!
1688 * Returns the contact's profession.
1689 *
1690 * \note This is a non-standard extension using the \c X-Profession field.
1691 *
1692 * \since 5.12
1693 */
1694 QString profession() const;
1695 /*!
1696 * Set the contact's profession.
1697 * @note This is a non-standard extension using the \c X-Profession field.
1698 * \since 5.12
1699 */
1700 void setProfession(const QString &profession);
1701
1702 /*!
1703 * Returns the contact's spouse's name.
1704 *
1705 * \note This is a non-standard extension using the \c X-SpousesName field.
1706 *
1707 * \since 5.12
1708 */
1709 QString spousesName() const;
1710 /*!
1711 * Set the contact's spouse's name.
1712 *
1713 * \note This is a non-standard extension using the \c X-SpousesName field.
1714 *
1715 * \since 5.12
1716 */
1717 void setSpousesName(const QString &spousesName);
1718
1719private:
1720 KCONTACTS_NO_EXPORT void setBirthdayProperty(const QDateTime &birthday);
1721
1722 class Private;
1723 QSharedDataPointer<Private> d;
1724};
1725
1726/*!
1727 * \relates KContacts::Addressee
1728 */
1729KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &, const Addressee &);
1730
1731/*!
1732 * \relates KContacts::Addressee
1733 */
1734KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &, Addressee &);
1735}
1736
1737#endif
1738

source code of kcontacts/src/addressee.h