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 /*!
471 * \property KContacts::Addressee::deathDate
472 */
473 Q_PROPERTY(QDateTime deathDate READ deathDate WRITE setDeathDate)
474
475 // ### the following properties are still missing:
476 // - logos, photos, sounds
477 // - keys
478 // - the list variants for nicks, titles, roles, orgs
479 // - timezone, secrecy, gender, kind, members, relationships, language
480 // - field groups, sourceUrls, calendarUrls
481
482public:
483 /*!
484 A list of addressee objects
485 */
486 typedef AddresseeList List;
487
488 /*!
489 Construct an empty address book entry.
490 */
491 Addressee();
492
493 /*!
494 Destroys the address book entry.
495 */
496 ~Addressee();
497
498 /*!
499 Copy constructor.
500 */
501 Addressee(const Addressee &other);
502
503 /*!
504 Assignment operator.
505
506 Returns a reference to \c this
507 */
508 Addressee &operator=(const Addressee &other);
509
510 /*!
511 Equality operator.
512
513 Returns \c true if \c this and the given addressee are equal,
514 otherwise \c false
515 */
516 bool operator==(const Addressee &other) const;
517
518 /*!
519 Not-equal operator.
520
521 Returns \c true if \c this and the given addressee are not equal,
522 otherwise \c false
523 */
524 bool operator!=(const Addressee &other) const;
525
526 /*!
527 Return if the address book entry is empty.
528 */
529 [[nodiscard]] bool isEmpty() const;
530
531 /*!
532 Set unique identifier.
533
534 \a uid the KABC unique identifier
535 */
536 void setUid(const QString &uid);
537
538 /*!
539 Return unique identifier.
540 */
541 [[nodiscard]] QString uid() const;
542
543 /*!
544 Return translated label for uid field.
545 */
546 static QString uidLabel();
547
548 /*!
549 Set name.
550 */
551 void setName(const QString &name);
552
553 /*!
554 Return name.
555 */
556 [[nodiscard]] QString name() const;
557
558 /*!
559 Return translated label for name field.
560 */
561 static QString nameLabel();
562
563 /*!
564 Set formatted name.
565 */
566 void setFormattedName(const QString &formattedName);
567
568 /*!
569 Return formatted name.
570 */
571 [[nodiscard]] QString formattedName() const;
572
573 /*!
574 Return translated label for formattedName field.
575 */
576 [[nodiscard]] static QString formattedNameLabel();
577
578 /*!
579 Set family name.
580 */
581 void setFamilyName(const QString &familyName);
582
583 /*!
584 Return family name.
585 */
586 [[nodiscard]] QString familyName() const;
587
588 /*!
589 Return translated label for familyName field.
590 */
591 [[nodiscard]] static QString familyNameLabel();
592
593 /*!
594 Set given name.
595 */
596 void setGivenName(const QString &givenName);
597
598 /*!
599 Return given name.
600 */
601 [[nodiscard]] QString givenName() const;
602
603 /*!
604 Return translated label for givenName field.
605 */
606 [[nodiscard]] static QString givenNameLabel();
607
608 /*!
609 Set additional names.
610 */
611 void setAdditionalName(const QString &additionalName);
612
613 /*!
614 Return additional names.
615 */
616 [[nodiscard]] QString additionalName() const;
617
618 /*!
619 Return translated label for additionalName field.
620 */
621 [[nodiscard]] static QString additionalNameLabel();
622
623 /*!
624 Set honorific prefixes.
625 */
626 void setPrefix(const QString &prefix);
627
628 /*!
629 Return honorific prefixes.
630 */
631 [[nodiscard]] QString prefix() const;
632
633 /*!
634 Return translated label for prefix field.
635 */
636 [[nodiscard]] static QString prefixLabel();
637
638 /*!
639 Set honorific suffixes.
640 */
641 void setSuffix(const QString &suffix);
642
643 /*!
644 Return honorific suffixes.
645 */
646 [[nodiscard]] QString suffix() const;
647
648 /*!
649 Return translated label for suffix field.
650 */
651 [[nodiscard]] static QString suffixLabel();
652
653 /*!
654 Set nick name.
655 */
656 void setNickName(const QString &nickName);
657
658 /*!
659 */
660 void setNickName(const NickName &nickName);
661
662 /*!
663 */
664 void insertExtraNickName(const NickName &nickName);
665
666 /*!
667 */
668 void setExtraNickNameList(const NickName::List &nickNameList);
669
670 /*!
671 */
672 [[nodiscard]] NickName::List extraNickNameList() const;
673
674 /*!
675 Return nick name.
676 */
677 [[nodiscard]] QString nickName() const;
678
679 /*!
680 Return translated label for nickName field.
681 */
682 [[nodiscard]] static QString nickNameLabel();
683
684 /*!
685 Set birthday (date and time). If withTime is false the time will be set
686 to midnight and birthdayHasTime() will return false afterwards.
687 \since 5.4
688 */
689 void setBirthday(const QDateTime &birthday, bool withTime = true);
690
691 /*!
692 Set birthday (date only). birthdayHasTime() will return false afterwards.
693 */
694 void setBirthday(const QDate &birthday);
695
696 /*!
697 Return birthday. (If a valid date has been set, birthday().time() will
698 always return a valid QTime!)
699 */
700 [[nodiscard]] QDateTime birthday() const;
701
702 /*!
703 Returns true if birthday has been set with a time. Returns false otherwise.
704 */
705 [[nodiscard]] bool birthdayHasTime() const;
706
707 /*!
708 Return translated label for birthday field.
709 */
710 [[nodiscard]] static QString birthdayLabel();
711
712 /*!
713 Return translated label for homeAddressStreet field.
714 */
715 [[nodiscard]] static QString homeAddressStreetLabel();
716
717 /*!
718 Return translated label for homeAddressPostOfficeBox field.
719 */
720 [[nodiscard]] static QString homeAddressPostOfficeBoxLabel();
721
722 /*!
723 Return translated label for homeAddressLocality field.
724 */
725 [[nodiscard]] static QString homeAddressLocalityLabel();
726
727 /*!
728 Return translated label for homeAddressRegion field.
729 */
730 [[nodiscard]] static QString homeAddressRegionLabel();
731
732 /*!
733 Return translated label for homeAddressPostalCode field.
734 */
735 [[nodiscard]] static QString homeAddressPostalCodeLabel();
736
737 /*!
738 Return translated label for homeAddressCountry field.
739 */
740 [[nodiscard]] static QString homeAddressCountryLabel();
741
742 /*!
743 Return translated label for homeAddressLabel field.
744 */
745 [[nodiscard]] static QString homeAddressLabelLabel();
746
747 /*!
748 Return translated label for businessAddressStreet field.
749 */
750 [[nodiscard]] static QString businessAddressStreetLabel();
751
752 /*!
753 Return translated label for businessAddressPostOfficeBox field.
754 */
755 [[nodiscard]] static QString businessAddressPostOfficeBoxLabel();
756
757 /*!
758 Return translated label for businessAddressLocality field.
759 */
760 [[nodiscard]] static QString businessAddressLocalityLabel();
761
762 /*!
763 Return translated label for businessAddressRegion field.
764 */
765 [[nodiscard]] static QString businessAddressRegionLabel();
766
767 /*!
768 Return translated label for businessAddressPostalCode field.
769 */
770 [[nodiscard]] static QString businessAddressPostalCodeLabel();
771
772 /*!
773 Return translated label for businessAddressCountry field.
774 */
775 [[nodiscard]] static QString businessAddressCountryLabel();
776
777 /*!
778 Return translated label for businessAddressLabel field.
779 */
780 [[nodiscard]] static QString businessAddressLabelLabel();
781
782 /*!
783 Return translated label for homePhone field.
784 */
785 [[nodiscard]] static QString homePhoneLabel();
786
787 /*!
788 Return translated label for businessPhone field.
789 */
790 [[nodiscard]] static QString businessPhoneLabel();
791
792 /*!
793 Return translated label for mobilePhone field.
794 */
795 [[nodiscard]] static QString mobilePhoneLabel();
796
797 /*!
798 Return translated label for homeFax field.
799 */
800 [[nodiscard]] static QString homeFaxLabel();
801
802 /*!
803 Return translated label for businessFax field.
804 */
805 [[nodiscard]] static QString businessFaxLabel();
806
807 /*!
808 Return translated label for carPhone field.
809 */
810 [[nodiscard]] static QString carPhoneLabel();
811
812 /*!
813 Return translated label for isdn field.
814 */
815 [[nodiscard]] static QString isdnLabel();
816
817 /*!
818 Return translated label for pager field.
819 */
820 [[nodiscard]] static QString pagerLabel();
821
822 /*!
823 Return translated label for email field.
824 */
825 [[nodiscard]] static QString emailLabel();
826
827 /*!
828 Set mail client.
829 */
830 void setMailer(const QString &mailer);
831
832 /*!
833 Return mail client.
834 */
835 [[nodiscard]] QString mailer() const;
836
837 /*!
838 Return translated label for mailer field.
839 */
840 [[nodiscard]] static QString mailerLabel();
841
842 /*!
843 Set time zone.
844 */
845 void setTimeZone(const TimeZone &timeZone);
846
847 /*!
848 Return time zone.
849 */
850 [[nodiscard]] TimeZone timeZone() const;
851
852 /*!
853 Return translated label for timeZone field.
854 */
855 [[nodiscard]] static QString timeZoneLabel();
856
857 /*!
858 Set geographic position.
859 */
860 void setGeo(const Geo &geo);
861
862 /*!
863 Return geographic position.
864 */
865 [[nodiscard]] Geo geo() const;
866
867 /*!
868 Return translated label for geo field.
869 */
870 [[nodiscard]] static QString geoLabel();
871
872 // Remove in kf6
873 /*!
874 Set title.
875 */
876 void setTitle(const QString &title);
877
878 /*!
879 */
880 void setTitle(const Title &title);
881
882 /*!
883 */
884 void insertExtraTitle(const Title &title);
885
886 /*!
887 */
888 void setExtraTitleList(const Title::List &urltitle);
889
890 /*!
891 */
892 [[nodiscard]] Title::List extraTitleList() const;
893
894 /*!
895 Return title.
896 */
897 [[nodiscard]] QString title() const;
898
899 /*!
900 Return translated label for title field.
901 */
902 [[nodiscard]] static QString titleLabel();
903
904 /*!
905 Set role.
906 */
907 void setRole(const QString &role);
908
909 /*!
910 */
911 void setRole(const Role &role);
912
913 /*!
914 */
915 void insertExtraRole(const Role &role);
916
917 /*!
918 */
919 void setExtraRoleList(const Role::List &roleList);
920
921 /*!
922 */
923 [[nodiscard]] Role::List extraRoleList() const;
924
925 /*!
926 Return role.
927 */
928 [[nodiscard]] QString role() const;
929
930 /*!
931 Return translated label for role field.
932 */
933 [[nodiscard]] static QString roleLabel();
934
935 // Remove in kf6
936 /*!
937 Set organization.
938 */
939 void setOrganization(const QString &organization);
940
941 /*!
942 */
943 void setOrganization(const Org &organization);
944
945 /*!
946 */
947 void insertExtraOrganization(const Org &organization);
948
949 /*!
950 */
951 void setExtraOrganizationList(const Org::List &orgList);
952
953 /*!
954 */
955 [[nodiscard]] Org::List extraOrganizationList() const;
956
957 /*!
958 Return organization.
959 */
960 [[nodiscard]] QString organization() const;
961
962 /*!
963 Return translated label for organization field.
964 */
965 [[nodiscard]] static QString organizationLabel();
966
967 /*!
968 Set department.
969 */
970 void setDepartment(const QString &department);
971
972 /*!
973 Return department.
974 */
975 [[nodiscard]] QString department() const;
976
977 /*!
978 Return translated label for department field.
979 */
980 [[nodiscard]] static QString departmentLabel();
981
982 /*!
983 Set note.
984 */
985 void setNote(const QString &note);
986
987 /*!
988 Return note.
989 */
990 [[nodiscard]] QString note() const;
991
992 /*!
993 Return translated label for note field.
994 */
995 [[nodiscard]] static QString noteLabel();
996
997 /*!
998 Set product identifier.
999 */
1000 void setProductId(const QString &productId);
1001
1002 /*!
1003 Return product identifier.
1004 */
1005 [[nodiscard]] QString productId() const;
1006
1007 /*!
1008 Return translated label for productId field.
1009 */
1010 [[nodiscard]] static QString productIdLabel();
1011
1012 /*!
1013 Set revision date.
1014 */
1015 void setRevision(const QDateTime &revision);
1016
1017 /*!
1018 Return revision date.
1019 */
1020 [[nodiscard]] QDateTime revision() const;
1021
1022 /*!
1023 Return translated label for revision field.
1024 */
1025 [[nodiscard]] static QString revisionLabel();
1026
1027 /*!
1028 Set sort string.
1029 */
1030 void setSortString(const QString &sortString);
1031
1032 /*!
1033 Return sort string.
1034 */
1035 [[nodiscard]] QString sortString() const;
1036
1037 /*!
1038 Return translated label for sortString field.
1039 */
1040 [[nodiscard]] static QString sortStringLabel();
1041
1042 /*!
1043 Set homepage.
1044 */
1045 void setUrl(const ResourceLocatorUrl &url);
1046 // kf6: remove it
1047 void setUrl(const QUrl &url);
1048
1049 /*!
1050 Return homepage.
1051 */
1052 [[nodiscard]] ResourceLocatorUrl url() const;
1053
1054 /*!
1055 Return translated label for url field.
1056 */
1057 [[nodiscard]] static QString urlLabel();
1058
1059 /*!
1060 Set security class.
1061 */
1062 void setSecrecy(const Secrecy &secrecy);
1063
1064 /*!
1065 Return security class.
1066 */
1067 [[nodiscard]] Secrecy secrecy() const;
1068
1069 /*!
1070 Return translated label for secrecy field.
1071 */
1072 [[nodiscard]] static QString secrecyLabel();
1073
1074 /*!
1075 Set logo.
1076 */
1077 void setLogo(const Picture &);
1078
1079 /*!
1080 Return logo.
1081 */
1082 [[nodiscard]] Picture logo() const;
1083
1084 /*!
1085 Return translated label for logo field.
1086 */
1087 [[nodiscard]] static QString logoLabel();
1088
1089 /*!
1090 Set photo.
1091 */
1092 void setPhoto(const Picture &photo);
1093
1094 /*!
1095 Return photo.
1096 */
1097 [[nodiscard]] Picture photo() const;
1098
1099 /*!
1100 Return translated label for photo field.
1101 */
1102 [[nodiscard]] static QString photoLabel();
1103
1104 /*!
1105 Set sound.
1106 */
1107 void setSound(const Sound &sound);
1108
1109 /*!
1110 Return sound.
1111 */
1112 [[nodiscard]] Sound sound() const;
1113
1114 /*!
1115 Return translated label for sound field.
1116 */
1117 [[nodiscard]] static QString soundLabel();
1118
1119 /*!
1120 Set name fields by parsing the given string and trying to associate the
1121 parts of the string with according fields. This function should probably
1122 be a bit more clever.
1123 */
1124 void setNameFromString(const QString &s);
1125
1126 /*!
1127 Return the name of the addressee. This is calculated from all the name
1128 fields.
1129 */
1130 [[nodiscard]] QString realName() const;
1131
1132 /*!
1133 Return the name that consists of all name parts.
1134 */
1135 [[nodiscard]] QString assembledName() const;
1136
1137 /*!
1138 Return email address including real name.
1139
1140 \a email Email address to be used to construct the full email string.
1141 If this is QString() the preferred email address is used.
1142 */
1143 [[nodiscard]] QString fullEmail(const QString &email = QString()) const;
1144
1145 /*!
1146 Adds an email address. If the email address (i.e. email.mail()) already
1147 exists in this addressee it won't be duplicated, instead email is assigned
1148 to it.
1149
1150 \since 5.88
1151 */
1152 void addEmail(const Email &email);
1153
1154 /*!
1155 Remove email address. If the email address doesn't exist, nothing happens.
1156
1157 \a email Email address to remove
1158 */
1159 void removeEmail(const QString &email);
1160
1161 /*!
1162 Return preferred email address. This is the first email address or the last
1163 one added with insertEmail() or addEmail() with a set preferred parameter.
1164 */
1165 [[nodiscard]] QString preferredEmail() const;
1166
1167 /*!
1168 Return list of all email addresses.
1169 */
1170 [[nodiscard]] QStringList emails() const;
1171
1172 /*!
1173 Set the emails to \a list.
1174 The first email address gets the preferred one!
1175 */
1176 void setEmails(const QStringList &list);
1177
1178 /*!
1179 Insert a phone number. If a phone number with the same id already exists
1180 in this addressee it is not duplicated.
1181
1182 \a phoneNumber The telephone number to insert to the addressee
1183 */
1184 void insertPhoneNumber(const PhoneNumber &phoneNumber);
1185
1186 /*!
1187 Remove phone number. If no phone number with the given id exists for this
1188 addressee, nothing happens.
1189
1190 \a phoneNumber The telephone number to remove from the addressee
1191 */
1192 void removePhoneNumber(const PhoneNumber &phoneNumber);
1193
1194 /*!
1195 Return phone number, which matches the given type.
1196
1197 \a type The type of phone number to get
1198 */
1199 [[nodiscard]] PhoneNumber phoneNumber(PhoneNumber::Type type) const;
1200
1201 /*!
1202 Return list of all phone numbers.
1203 */
1204 [[nodiscard]] PhoneNumber::List phoneNumbers() const;
1205
1206 void setPhoneNumbers(const PhoneNumber::List &phoneNumbers);
1207
1208 /*!
1209 Return list of phone numbers with a special type.
1210
1211 \a type The type of phone number to get
1212 */
1213 [[nodiscard]] PhoneNumber::List phoneNumbers(PhoneNumber::Type type) const;
1214
1215 /*!
1216 Return phone number with the given id.
1217
1218 \a id The identifier of the phone number to look for.
1219 See PhoneNumber::id()
1220 */
1221 [[nodiscard]] PhoneNumber findPhoneNumber(const QString &id) const;
1222
1223 /*!
1224 Insert a key. If a key with the same id already exists
1225 in this addressee it is not duplicated.
1226
1227 \a key The key to insert
1228 */
1229 void insertKey(const Key &key);
1230
1231 /*!
1232 Remove a key. If no key with the given id exists for this
1233 addressee, nothing happens.
1234
1235 \a key The key to remove
1236 */
1237 void removeKey(const Key &key);
1238
1239 /*!
1240 Return key, which matches the given type.
1241 If \a type == Key::Custom you can specify a string
1242 that should match. If you leave the string empty, the first
1243 key with a custom value is returned.
1244
1245 \a type The type of key to look for
1246
1247 \a customTypeString A string to match custom keys against when
1248 \a type is \c Key::Custom
1249 */
1250 [[nodiscard]] Key key(Key::Type type, const QString &customTypeString = QString()) const;
1251
1252 /*!
1253 Return list of all keys.
1254 */
1255 [[nodiscard]] Key::List keys() const;
1256
1257 /*!
1258 Set the list of keys
1259 \a keys The keys to be set.
1260 */
1261 void setKeys(const Key::List &keys);
1262
1263 /*!
1264 Return list of keys with a special type.
1265 If \a type == Key::Custom you can specify a string
1266 that should match. If you leave the string empty, all custom
1267 keys will be returned.
1268
1269 \a type The type of key to look for
1270
1271 \a customTypeString A string to match custom keys against when
1272 \a type is \c Key::Custom
1273 */
1274 [[nodiscard]] Key::List keys(Key::Type type, const QString &customTypeString = QString()) const;
1275
1276 /*!
1277 Return key with the given id.
1278
1279 \a id The identifier of the key to look for. See Key::id()
1280 */
1281 [[nodiscard]] Key findKey(const QString &id) const;
1282
1283 /*!
1284 Insert an address. If an address with the same id already exists
1285 in this addressee it is not duplicated.
1286
1287 \a address The address to insert
1288 */
1289 void insertAddress(const Address &address);
1290
1291 /*!
1292 Remove address. If no address with the given id exists for this
1293 addressee, nothing happens.
1294
1295 \a address The address to remove
1296 */
1297 void removeAddress(const Address &address);
1298
1299 /*!
1300 Set the addressee
1301
1302 \a addresses The new addresses
1303 \since 5.100
1304 */
1305 void setAddresses(const Address::List &addresses);
1306
1307 /*!
1308 Return address, which matches the given type.
1309
1310 \a type The type of address to look for
1311 */
1312 [[nodiscard]] Address address(Address::Type type) const;
1313
1314 /*!
1315 Return list of all addresses.
1316 */
1317 [[nodiscard]] Address::List addresses() const;
1318
1319 /*!
1320 Return list of addresses with a special type.
1321
1322 \a type The type of addresses to look for
1323 */
1324 [[nodiscard]] Address::List addresses(Address::Type type) const;
1325
1326 /*!
1327 Return address with the given id.
1328
1329 \a id The identifier of the address to look for. See Address::id()
1330 */
1331 [[nodiscard]] Address findAddress(const QString &id) const;
1332
1333 /*!
1334 Insert category. If the category already exists it is not duplicated.
1335 */
1336 void insertCategory(const QString &category);
1337
1338 /*!
1339 Remove category.
1340 */
1341 void removeCategory(const QString &category);
1342
1343 /*!
1344 Return, if addressee has the given category.
1345 */
1346 [[nodiscard]] bool hasCategory(const QString &category) const;
1347
1348 /*!
1349 Set categories to given value.
1350 */
1351 void setCategories(const QStringList &category);
1352
1353 /*!
1354 Return list of all set categories.
1355 */
1356 [[nodiscard]] QStringList categories() const;
1357
1358 /*!
1359 Insert custom entry. The entry is identified by the name of the inserting
1360 application and a unique name. If an entry with the given app and name
1361 already exists its value is replaced with the new given value.
1362
1363 An empty value isn't allowed (nothing happens if this is called with
1364 any of the three arguments being empty)
1365
1366 \a app Name of the application inserting this custom entry
1367
1368 \a name Name of this application specific custom entry
1369
1370 \a value Value of this application specific custom entry
1371 */
1372 void insertCustom(const QString &app, const QString &name, const QString &value);
1373
1374 /*!
1375 Remove custom entry.
1376
1377 \a app Name of the application which has inserted this custom entry
1378
1379 \a name Name of this application specific custom entry
1380 */
1381 void removeCustom(const QString &app, const QString &name);
1382
1383 /*!
1384 Return value of custom entry, identified by app and entry name.
1385
1386 \a app Name of the application which has inserted this custom entry
1387
1388 \a name Name of this application specific custom entry
1389 */
1390 [[nodiscard]] QString custom(const QString &app, const QString &name) const;
1391
1392 /*!
1393 Set all custom entries.
1394 */
1395 void setCustoms(const QStringList &customs);
1396
1397 /*!
1398 Return list of all custom entries.
1399
1400 The format of the custom entries is 'app-key:value' and the list is sorted
1401 alphabetically by 'app-key'.
1402 */
1403 [[nodiscard]] QStringList customs() const;
1404
1405 /*!
1406 Parse full email address. The result is given back in fullName and email.
1407
1408 \a rawEmail The input string to parse for name and email
1409
1410 \a fullName The name part of the \a rawEmail input, if it contained one
1411
1412 \a email The email part of the \a rawEmail input, if it contained one
1413 */
1414 static void parseEmailAddress(const QString &rawEmail, QString &fullName, QString &email);
1415
1416 /*!
1417 Returns string representation of the addressee.
1418 */
1419 [[nodiscard]] QString toString() const;
1420
1421 /*!
1422 Mark addressee as changed.
1423
1424 \a value Sets the status indicating changed data
1425 */
1426 void setChanged(bool value);
1427
1428 /*!
1429 Return whether the addressee is changed.
1430 */
1431 [[nodiscard]] bool changed() const;
1432
1433 /*!
1434 Returns the MIME type used for Addressees
1435 */
1436 [[nodiscard]] static QString mimeType();
1437
1438 [[nodiscard]] KContacts::Email::List emailList() const;
1439 void setEmailList(const Email::List &list);
1440
1441 /*!
1442 * Remove Language
1443 */
1444 void removeLang(const QString &language);
1445 /*!
1446 * Insert Language
1447 */
1448 void insertLang(const Lang &language);
1449 /*!
1450 * Returns List of lang
1451 */
1452 [[nodiscard]] Lang::List langs() const;
1453 /*!
1454 */
1455 void setLangs(const Lang::List &langs);
1456
1457 /*!
1458 */
1459 void setGender(const Gender &gender);
1460
1461 /*!
1462 */
1463 [[nodiscard]] Gender gender() const;
1464
1465 /*!
1466 */
1467 [[nodiscard]] QString kind() const;
1468
1469 /*!
1470 */
1471 void setKind(const QString &kind);
1472
1473 /*!
1474 */
1475 void insertCalendarUrl(const CalendarUrl &calendarUrl);
1476
1477 /*!
1478 */
1479 [[nodiscard]] CalendarUrl::List calendarUrlList() const;
1480
1481 /*!
1482 */
1483 void insertExtraSound(const Sound &sound);
1484
1485 /*!
1486 */
1487 void setExtraSoundList(const Sound::List &soundList);
1488
1489 /*!
1490 */
1491 [[nodiscard]] Sound::List extraSoundList() const;
1492
1493 /*!
1494 */
1495 void insertExtraPhoto(const Picture &picture);
1496
1497 /*!
1498 */
1499 void setExtraPhotoList(const Picture::List &pictureList);
1500
1501 /*!
1502 */
1503 [[nodiscard]] Picture::List extraPhotoList() const;
1504
1505 /*!
1506 */
1507 void insertExtraLogo(const Picture &);
1508
1509 /*!
1510 */
1511 void setExtraLogoList(const Picture::List &logoList);
1512
1513 /*!
1514 */
1515 [[nodiscard]] Picture::List extraLogoList() const;
1516
1517 /*!
1518 */
1519 [[nodiscard]] ResourceLocatorUrl::List extraUrlList() const;
1520
1521 /*!
1522 */
1523 void setExtraUrlList(const ResourceLocatorUrl::List &urlList);
1524
1525 /*!
1526 */
1527 void insertExtraUrl(const ResourceLocatorUrl &url);
1528
1529 // Member
1530 /*!
1531 */
1532 void insertMember(const QString &member);
1533
1534 /*!
1535 */
1536 void setMembers(const QStringList &c);
1537
1538 /*!
1539 */
1540 [[nodiscard]] QStringList members() const;
1541
1542 // Relation
1543 /*!
1544 */
1545 void insertRelationship(const Related &related);
1546
1547 /*!
1548 */
1549 void setRelationships(const Related::List &c);
1550
1551 /*!
1552 */
1553 [[nodiscard]] Related::List relationships() const;
1554
1555 // Source
1556 /*!
1557 */
1558 void insertSourceUrl(const QUrl &url);
1559
1560 /*!
1561 */
1562 void setSourcesUrlList(const QList<QUrl> &urlList);
1563
1564 /*!
1565 */
1566 [[nodiscard]] QList<QUrl> sourcesUrlList() const;
1567
1568 // Impp
1569 /*!
1570 */
1571 [[nodiscard]] Impp::List imppList() const;
1572
1573 /*!
1574 */
1575 void setImppList(const Impp::List &imppList);
1576
1577 /*!
1578 */
1579 void insertImpp(const Impp &impp);
1580
1581 // FieldGroup
1582 /*!
1583 */
1584 [[nodiscard]] FieldGroup::List fieldGroupList() const;
1585
1586 /*!
1587 */
1588 void setFieldGroupList(const FieldGroup::List &fieldGroupList);
1589
1590 /*!
1591 */
1592 void insertFieldGroup(const FieldGroup &fieldGroup);
1593
1594 // ClientPidMap
1595 /*!
1596 */
1597 [[nodiscard]] ClientPidMap::List clientPidMapList() const;
1598
1599 /*!
1600 */
1601 void setClientPidMapList(const ClientPidMap::List &clientpidmaplist);
1602
1603 /*!
1604 */
1605 void insertClientPidMap(const ClientPidMap &clientpidmap);
1606
1607 /*!
1608 * Returns the contact's anniversary date.
1609 *
1610 * \note This is a non-standard extension using the \c X-Anniversary field.
1611 *
1612 * \since 5.12
1613 */
1614 [[nodiscard]] QDate anniversary() const;
1615 /*!
1616 * Sets the contact's anniversary date.
1617 *
1618 * \note This is a non-standard extension using the \c X-Anniversary field.
1619 *
1620 * \since 5.12
1621 */
1622 void setAnniversary(const QDate &anniversary);
1623
1624 /*!
1625 * Returns the contact's assistant's name.
1626 *
1627 * \note This is a non-standard extension using the \c X-AssistantsName field.
1628 *
1629 * \since 5.12
1630 */
1631 [[nodiscard]] QString assistantsName() const;
1632 /*!
1633 * Set the contact's assistant's name.
1634 *
1635 * \note This is a non-standard extension using the \c X-AssistantsName field.
1636 *
1637 * \since 5.12
1638 */
1639 void setAssistantsName(const QString &assistantsName);
1640
1641 /*!
1642 * Returns the contact's blog feed.
1643 *
1644 * \note This is a non-standard extension using the \c BlogFeed field.
1645 *
1646 * \since 5.12
1647 */
1648 [[nodiscard]] QUrl blogFeed() const;
1649 /*!
1650 * Set the contact's blog feed.
1651 *
1652 * \note This is a non-standard extension using the \c BlogFeed field.
1653 *
1654 * \since 5.12
1655 */
1656 void setBlogFeed(const QUrl &blogFeed);
1657
1658 /*!
1659 * Returns the contact's manager's name.
1660 *
1661 * \note This is a non-standard extension using the \c X-ManagersName field.
1662 *
1663 * \since 5.12
1664 */
1665 [[nodiscard]] QString managersName() const;
1666 /*!
1667 * Set the contact's manager's name.
1668 *
1669 * \note This is a non-standard extension using the \c X-ManagersName field.
1670 *
1671 * \since 5.12
1672 */
1673 void setManagersName(const QString &managersName);
1674
1675 /*!
1676 * Returns the contact's office.
1677 *
1678 * \note This is a non-standard extension using the \c X-Office field.
1679 *
1680 * \since 5.12
1681 */
1682 [[nodiscard]] QString office() const;
1683 /*!
1684 * Set the contact's office.
1685 *
1686 * \note This is a non-standard extension using the \c X-Office field.
1687 *
1688 * \since 5.12
1689 */
1690 void setOffice(const QString &office);
1691
1692 /*!
1693 * Returns the contact's profession.
1694 *
1695 * \note This is a non-standard extension using the \c X-Profession field.
1696 *
1697 * \since 5.12
1698 */
1699 [[nodiscard]] QString profession() const;
1700 /*!
1701 * Set the contact's profession.
1702 * @note This is a non-standard extension using the \c X-Profession field.
1703 * \since 5.12
1704 */
1705 void setProfession(const QString &profession);
1706
1707 /*!
1708 * Returns the contact's spouse's name.
1709 *
1710 * \note This is a non-standard extension using the \c X-SpousesName field.
1711 *
1712 * \since 5.12
1713 */
1714 [[nodiscard]] QString spousesName() const;
1715 /*!
1716 * Set the contact's spouse's name.
1717 *
1718 * \note This is a non-standard extension using the \c X-SpousesName field.
1719 *
1720 * \since 5.12
1721 */
1722 void setSpousesName(const QString &spousesName);
1723
1724 /*!
1725 * Returns the death's date.
1726 *
1727 * \note This is a non-standard extension using the \c X-SpousesName field.
1728 *
1729 * \since 6.20
1730 */
1731 [[nodiscard]] QDateTime deathDate() const;
1732 /*!
1733 * Set the death's date
1734 *
1735 * \note This is a vcard4 extension
1736 *
1737 * \since 6.20
1738 */
1739 void setDeathDate(const QDateTime &deathDate);
1740
1741private:
1742 KCONTACTS_NO_EXPORT void setBirthdayProperty(const QDateTime &birthday);
1743
1744 class Private;
1745 QSharedDataPointer<Private> d;
1746};
1747
1748/*!
1749 * \relates KContacts::Addressee
1750 */
1751KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &, const Addressee &);
1752
1753/*!
1754 * \relates KContacts::Addressee
1755 */
1756KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &, Addressee &);
1757}
1758
1759#endif
1760

source code of kcontacts/src/addressee.h