src/people/person.h

0001 /*
0002  * SPDX-FileCopyrightText: 2021 Daniel Vrátil <dvratil@kde.org>
0003  * SPDX-FileCopyrightText: 2022 Claudio Cambra <claudio.cambra@kde.org>
0004  *
0005  * SPDX-License-Identifier: LGPL-2.1-only
0006  * SPDX-License-Identifier: LGPL-3.0-only
0007  * SPDX-License-Identifier: LicenseRef-KDE-Accepted-LGPL
0008  */
0009
0010 #pragma once
0011
0012 #include "object.h"
0013 #include "types.h"
0014 #include "kgapipeople_export.h"
0015
0016 #include <QList>
0017 #include <QString>
0018
0019 #include <QSharedPointer>
0020
0021 #include <optional>
0022
0023 class QJsonObject;
0024 class QJsonValue;
0025
0026 namespace KContacts
0027 {
0028 class Addressee;
0029 }
0030
0031 namespace KGAPI2::People
0032 {
0033 class Person;
0034 using PersonPtr = QSharedPointer<Person>;
0035
0036 class Address;
0037 class AgeRangeType;
0038 class Biography;
0039 class Birthday;
0040 class BraggingRights;
0041 class CalendarUrl;
0042 class ClientData;
0043 class CoverPhoto;
0044 class EmailAddress;
0045 class Event;
0046 class ExternalId;
0047 class FileAs;
0048 class Gender;
0049 class ImClient;
0050 class Interest;
0051 class Location;
0052 class Membership;
0053 class MiscKeyword;
0054 class Name;
0055 class Nickname;
0056 class Occupation;
0057 class Organization;
0058 class PersonLocale;
0059 class PersonMetadata;
0060 class PhoneNumber;
0061 class Photo;
0062 class Relation;
0063 class RelationshipInterest;
0064 class RelationshipStatus;
0065 class Residence;
0066 class SipAddress;
0067 class Skill;
0068 class Tagline;
0069 class Url;
0070 class UserDefined;
0071
0072 /**
0073  * Information about a person merged from various data sources such as the
0074  * authenticated user's contacts and profile data. Most fields can have multiple
0075  * items. The items in a field have no guaranteed order, but each non-empty field
0076  * is guaranteed to have exactly one field with `metadata.primary` set to true.
0077  *
0078  * @see https://developers.google.com/people/api/rest/v1/people#person
0079  * @since 5.23.0
0080  **/
0081 class KGAPIPEOPLE_EXPORT Person : public KGAPI2::Object
0082 {
0083 public:
0084     enum class AgeRange {
0085         AGE_RANGE_UNSPECIFIED, ///< Unspecified.
0086         LESS_THAN_EIGHTEEN, ///< Younger than eighteen.
0087         EIGHTEEN_TO_TWENTY, ///< Between eighteen and twenty.
0088         TWENTY_ONE_OR_OLDER, ///< Twenty-one and older.
0089     };
0090
0091     /** Construcuts a new Person **/
0092     explicit Person();
0093     /** Destructor. **/
0094     ~Person();
0095
0096     static PersonPtr fromKContactsAddressee(const KContacts::Addressee &addressee);
0097     KContacts::Addressee toKContactsAddressee() const;
0098
0099     bool operator==(const Person &) const;
0100     bool operator!=(const Person &) const;
0101
0102     /** The person's nicknames. **/
0103     [[nodiscard]] QList<Nickname> nicknames() const;
0104     /** Sets value of the nicknames property. **/
0105     void setNicknames(const QList<Nickname> &value);
0106     /** Appends the given @c value to the list of nicknames. **/
0107     void addNickname(const Nickname &value);
0108     /** Removes the given @c value from the list of nicknames if it exists. **/
0109     void removeNickname(const Nickname &value);
0110     /** Clears the list of nicknames. **/
0111     void clearNicknames();
0112
0113     /** The person's email addresses. For `people.connections.list` and `otherContacts.list` the number of email addresses is limited to 100. If a Person has
0114      * more email addresses the entire set can be obtained by calling GetPeople. **/
0115     [[nodiscard]] QList<EmailAddress> emailAddresses() const;
0116     /** Sets value of the emailAddresses property. **/
0117     void setEmailAddresses(const QList<EmailAddress> &value);
0118     /** Appends the given @c value to the list of emailAddresses. **/
0119     void addEmailAddress(const EmailAddress &value);
0120     /** Removes the given @c value from the list of emailAddresses if it exists. **/
0121     void removeEmailAddress(const EmailAddress &value);
0122     /** Clears the list of emailAddresses. **/
0123     void clearEmailAddresses();
0124
0125     /** The person's client data. **/
0126     [[nodiscard]] QList<ClientData> clientData() const;
0127     /** Sets value of the clientData property. **/
0128     void setClientData(const QList<ClientData> &value);
0129     /** Appends the given @c value to the list of clientData. **/
0130     void addClientData(const ClientData &value);
0131     /** Removes the given @c value from the list of clientData if it exists. **/
0132     void removeClientData(const ClientData &value);
0133     /** Clears the list of clientData. **/
0134     void clearClientData();
0135
0136     /** **DEPRECATED**: No data will be returned The person's bragging rights. **/
0137     [[nodiscard]] QList<BraggingRights> braggingRights() const;
0138     /** Sets value of the braggingRights property. **/
0139     void setBraggingRights(const QList<BraggingRights> &value);
0140     /** Appends the given @c value to the list of braggingRights. **/
0141     void addBraggingRights(const BraggingRights &value);
0142     /** Removes the given @c value from the list of braggingRights if it exists. **/
0143     void removeBraggingRights(const BraggingRights &value);
0144     /** Clears the list of braggingRights. **/
0145     void clearBraggingRights();
0146
0147     /** Output only. **DEPRECATED**: No data will be returned The person's relationship statuses. **/
0148     [[nodiscard]] QList<RelationshipStatus> relationshipStatuses() const;
0149
0150     /** The person's birthdays. This field is a singleton for contact sources. **/
0151     [[nodiscard]] QList<Birthday> birthdays() const;
0152     /** Sets value of the birthdays property. **/
0153     void setBirthdays(const QList<Birthday> &value);
0154     /** Appends the given @c value to the list of birthdays. **/
0155     void addBirthday(const Birthday &value);
0156     /** Removes the given @c value from the list of birthdays if it exists. **/
0157     void removeBirthday(const Birthday &value);
0158     /** Clears the list of birthdays. **/
0159     void clearBirthdays();
0160
0161     /** The person's relations. **/
0162     [[nodiscard]] QList<Relation> relations() const;
0163     /** Sets value of the relations property. **/
0164     void setRelations(const QList<Relation> &value);
0165     /** Appends the given @c value to the list of relations. **/
0166     void addRelation(const Relation &value);
0167     /** Removes the given @c value from the list of relations if it exists. **/
0168     void removeRelation(const Relation &value);
0169     /** Clears the list of relations. **/
0170     void clearRelations();
0171
0172     /** The person's locale preferences. **/
0173     [[nodiscard]] QList<PersonLocale> locales() const;
0174     /** Sets value of the locales property. **/
0175     void setLocales(const QList<PersonLocale> &value);
0176     /** Appends the given @c value to the list of locales. **/
0177     void addPersonLocale(const PersonLocale &value);
0178     /** Removes the given @c value from the list of locales if it exists. **/
0179     void removePersonLocale(const PersonLocale &value);
0180     /** Clears the list of locales. **/
0181     void clearLocales();
0182
0183     /** The person's locations. **/
0184     [[nodiscard]] QList<Location> locations() const;
0185     /** Sets value of the locations property. **/
0186     void setLocations(const QList<Location> &value);
0187     /** Appends the given @c value to the list of locations. **/
0188     void addLocation(const Location &value);
0189     /** Removes the given @c value from the list of locations if it exists. **/
0190     void removeLocation(const Location &value);
0191     /** Clears the list of locations. **/
0192     void clearLocations();
0193
0194     /** The person's external IDs. **/
0195     [[nodiscard]] QList<ExternalId> externalIds() const;
0196     /** Sets value of the externalIds property. **/
0197     void setExternalIds(const QList<ExternalId> &value);
0198     /** Appends the given @c value to the list of externalIds. **/
0199     void addExternalId(const ExternalId &value);
0200     /** Removes the given @c value from the list of externalIds if it exists. **/
0201     void removeExternalId(const ExternalId &value);
0202     /** Clears the list of externalIds. **/
0203     void clearExternalIds();
0204
0205     /** Output only. The person's age ranges. **/
0206     [[nodiscard]] QList<AgeRangeType> ageRanges() const;
0207
0208     /** Output only. **DEPRECATED**: No data will be returned The person's taglines. **/
0209     [[nodiscard]] QList<Tagline> taglines() const;
0210
0211     /** The person's user defined data. **/
0212     [[nodiscard]] QList<UserDefined> userDefined() const;
0213     /** Sets value of the userDefined property. **/
0214     void setUserDefined(const QList<UserDefined> &value);
0215     /** Appends the given @c value to the list of userDefined. **/
0216     void addUserDefined(const UserDefined &value);
0217     /** Removes the given @c value from the list of userDefined if it exists. **/
0218     void removeUserDefined(const UserDefined &value);
0219     /** Clears the list of userDefined. **/
0220     void clearUserDefined();
0221
0222     /** The person's biographies. This field is a singleton for contact sources. **/
0223     [[nodiscard]] QList<Biography> biographies() const;
0224     /** Sets value of the biographies property. **/
0225     void setBiographies(const QList<Biography> &value);
0226     /** Appends the given @c value to the list of biographies. **/
0227     void addBiography(const Biography &value);
0228     /** Removes the given @c value from the list of biographies if it exists. **/
0229     void removeBiography(const Biography &value);
0230     /** Clears the list of biographies. **/
0231     void clearBiographies();
0232
0233     /** The person's SIP addresses. **/
0234     [[nodiscard]] QList<SipAddress> sipAddresses() const;
0235     /** Sets value of the sipAddresses property. **/
0236     void setSipAddresses(const QList<SipAddress> &value);
0237     /** Appends the given @c value to the list of sipAddresses. **/
0238     void addSipAddress(const SipAddress &value);
0239     /** Removes the given @c value from the list of sipAddresses if it exists. **/
0240     void removeSipAddress(const SipAddress &value);
0241     /** Clears the list of sipAddresses. **/
0242     void clearSipAddresses();
0243
0244     /** The person's group memberships. **/
0245     [[nodiscard]] QList<Membership> memberships() const;
0246     /** Sets value of the memberships property. **/
0247     void setMemberships(const QList<Membership> &value);
0248     /** Appends the given @c value to the list of memberships. **/
0249     void addMembership(const Membership &value);
0250     /** Removes the given @c value from the list of memberships if it exists. **/
0251     void removeMembership(const Membership &value);
0252     /** Clears the list of memberships. **/
0253     void clearMemberships();
0254
0255     /** The person's skills. **/
0256     [[nodiscard]] QList<Skill> skills() const;
0257     /** Sets value of the skills property. **/
0258     void setSkills(const QList<Skill> &value);
0259     /** Appends the given @c value to the list of skills. **/
0260     void addSkill(const Skill &value);
0261     /** Removes the given @c value from the list of skills if it exists. **/
0262     void removeSkill(const Skill &value);
0263     /** Clears the list of skills. **/
0264     void clearSkills();
0265
0266     /** **DEPRECATED**: (Please use `person.locations` instead) The person's residences. **/
0267     [[nodiscard]] QList<Residence> residences() const;
0268     /** Sets value of the residences property. **/
0269     void setResidences(const QList<Residence> &value);
0270     /** Appends the given @c value to the list of residences. **/
0271     void addResidence(const Residence &value);
0272     /** Removes the given @c value from the list of residences if it exists. **/
0273     void removeResidence(const Residence &value);
0274     /** Clears the list of residences. **/
0275     void clearResidences();
0276
0277     /** The person's names. This field is a singleton for contact sources. **/
0278     [[nodiscard]] QList<Name> names() const;
0279     /** Sets value of the names property. **/
0280     void setNames(const QList<Name> &value);
0281     /** Appends the given @c value to the list of names. **/
0282     void addName(const Name &value);
0283     /** Removes the given @c value from the list of names if it exists. **/
0284     void removeName(const Name &value);
0285     /** Clears the list of names. **/
0286     void clearNames();
0287
0288     /** The person's calendar URLs. **/
0289     [[nodiscard]] QList<CalendarUrl> calendarUrls() const;
0290     /** Sets value of the calendarUrls property. **/
0291     void setCalendarUrls(const QList<CalendarUrl> &value);
0292     /** Appends the given @c value to the list of calendarUrls. **/
0293     void addCalendarUrl(const CalendarUrl &value);
0294     /** Removes the given @c value from the list of calendarUrls if it exists. **/
0295     void removeCalendarUrl(const CalendarUrl &value);
0296     /** Clears the list of calendarUrls. **/
0297     void clearCalendarUrls();
0298
0299     /** Output only. The person's cover photos. **/
0300     [[nodiscard]] QList<CoverPhoto> coverPhotos() const;
0301
0302     /** The person's street addresses. **/
0303     [[nodiscard]] QList<Address> addresses() const;
0304     /** Sets value of the addresses property. **/
0305     void setAddresses(const QList<Address> &value);
0306     /** Appends the given @c value to the list of addresses. **/
0307     void addAddress(const Address &value);
0308     /** Removes the given @c value from the list of addresses if it exists. **/
0309     void removeAddress(const Address &value);
0310     /** Clears the list of addresses. **/
0311     void clearAddresses();
0312
0313     /** The [HTTP entity tag](https://en.wikipedia.org/wiki/HTTP_ETag) of the resource. Used for web cache validation. **/
0314     [[nodiscard]] QString etag() const;
0315     /** Sets value of the etag property. **/
0316     void setEtag(const QString &value);
0317
0318     /** The person's phone numbers. For `people.connections.list` and `otherContacts.list` the number of phone numbers is limited to 100. If a Person has more
0319      * phone numbers the entire set can be obtained by calling GetPeople. **/
0320     [[nodiscard]] QList<PhoneNumber> phoneNumbers() const;
0321     /** Sets value of the phoneNumbers property. **/
0322     void setPhoneNumbers(const QList<PhoneNumber> &value);
0323     /** Appends the given @c value to the list of phoneNumbers. **/
0324     void addPhoneNumber(const PhoneNumber &value);
0325     /** Removes the given @c value from the list of phoneNumbers if it exists. **/
0326     void removePhoneNumber(const PhoneNumber &value);
0327     /** Clears the list of phoneNumbers. **/
0328     void clearPhoneNumbers();
0329
0330     /** The person's instant messaging clients. **/
0331     [[nodiscard]] QList<ImClient> imClients() const;
0332     /** Sets value of the imClients property. **/
0333     void setImClients(const QList<ImClient> &value);
0334     /** Appends the given @c value to the list of imClients. **/
0335     void addImClient(const ImClient &value);
0336     /** Removes the given @c value from the list of imClients if it exists. **/
0337     void removeImClient(const ImClient &value);
0338     /** Clears the list of imClients. **/
0339     void clearImClients();
0340
0341     /** The person's events. **/
0342     [[nodiscard]] QList<Event> events() const;
0343     /** Sets value of the events property. **/
0344     void setEvents(const QList<Event> &value);
0345     /** Appends the given @c value to the list of events. **/
0346     void addEvent(const Event &value);
0347     /** Removes the given @c value from the list of events if it exists. **/
0348     void removeEvent(const Event &value);
0349     /** Clears the list of events. **/
0350     void clearEvents();
0351
0352     /** Output only. The person's photos. **/
0353     [[nodiscard]] QList<Photo> photos() const;
0354
0355     /** The person's occupations. **/
0356     [[nodiscard]] QList<Occupation> occupations() const;
0357     /** Sets value of the occupations property. **/
0358     void setOccupations(const QList<Occupation> &value);
0359     /** Appends the given @c value to the list of occupations. **/
0360     void addOccupation(const Occupation &value);
0361     /** Removes the given @c value from the list of occupations if it exists. **/
0362     void removeOccupation(const Occupation &value);
0363     /** Clears the list of occupations. **/
0364     void clearOccupations();
0365
0366     /** The person's miscellaneous keywords. **/
0367     [[nodiscard]] QList<MiscKeyword> miscKeywords() const;
0368     /** Sets value of the miscKeywords property. **/
0369     void setMiscKeywords(const QList<MiscKeyword> &value);
0370     /** Appends the given @c value to the list of miscKeywords. **/
0371     void addMiscKeyword(const MiscKeyword &value);
0372     /** Removes the given @c value from the list of miscKeywords if it exists. **/
0373     void removeMiscKeyword(const MiscKeyword &value);
0374     /** Clears the list of miscKeywords. **/
0375     void clearMiscKeywords();
0376
0377     /** Output only. **DEPRECATED**: No data will be returned The person's relationship interests. **/
0378     [[nodiscard]] QList<RelationshipInterest> relationshipInterests() const;
0379
0380     /** The resource name for the person, assigned by the server. An ASCII string with a max length of 27 characters, in the form of `people/{person_id}`. **/
0381     [[nodiscard]] QString resourceName() const;
0382     /** Sets value of the resourceName property. **/
0383     void setResourceName(const QString &value);
0384
0385     /** The person's interests. **/
0386     [[nodiscard]] QList<Interest> interests() const;
0387     /** Sets value of the interests property. **/
0388     void setInterests(const QList<Interest> &value);
0389     /** Appends the given @c value to the list of interests. **/
0390     void addInterest(const Interest &value);
0391     /** Removes the given @c value from the list of interests if it exists. **/
0392     void removeInterest(const Interest &value);
0393     /** Clears the list of interests. **/
0394     void clearInterests();
0395
0396     /** The person's past or current organizations. **/
0397     [[nodiscard]] QList<Organization> organizations() const;
0398     /** Sets value of the organizations property. **/
0399     void setOrganizations(const QList<Organization> &value);
0400     /** Appends the given @c value to the list of organizations. **/
0401     void addOrganization(const Organization &value);
0402     /** Removes the given @c value from the list of organizations if it exists. **/
0403     void removeOrganization(const Organization &value);
0404     /** Clears the list of organizations. **/
0405     void clearOrganizations();
0406
0407     /** The person's associated URLs. **/
0408     [[nodiscard]] QList<Url> urls() const;
0409     /** Sets value of the urls property. **/
0410     void setUrls(const QList<Url> &value);
0411     /** Appends the given @c value to the list of urls. **/
0412     void addUrl(const Url &value);
0413     /** Removes the given @c value from the list of urls if it exists. **/
0414     void removeUrl(const Url &value);
0415     /** Clears the list of urls. **/
0416     void clearUrls();
0417
0418     /** The person's genders. This field is a singleton for contact sources. **/
0419     [[nodiscard]] QList<Gender> genders() const;
0420     /** Sets value of the genders property. **/
0421     void setGenders(const QList<Gender> &value);
0422     /** Appends the given @c value to the list of genders. **/
0423     void addGender(const Gender &value);
0424     /** Removes the given @c value from the list of genders if it exists. **/
0425     void removeGender(const Gender &value);
0426     /** Clears the list of genders. **/
0427     void clearGenders();
0428
0429     /** The person's file-ases. **/
0430     [[nodiscard]] QList<FileAs> fileAses() const;
0431     /** Sets value of the fileAses property. **/
0432     void setFileAses(const QList<FileAs> &value);
0433     /** Appends the given @c value to the list of fileAses. **/
0434     void addFileAs(const FileAs &value);
0435     /** Removes the given @c value from the list of fileAses if it exists. **/
0436     void removeFileAs(const FileAs &value);
0437     /** Clears the list of fileAses. **/
0438     void clearFileAses();
0439
0440     /** Output only. **DEPRECATED** (Please use `person.ageRanges` instead) The person's age range. **/
0441     [[nodiscard]] Person::AgeRange ageRange() const;
0442
0443     /** Output only. Metadata about the person. **/
0444     [[nodiscard]] PersonMetadata metadata() const;
0445
0446     [[nodiscard]] static PersonPtr fromJSON(const QJsonObject &obj);
0447     [[nodiscard]] QJsonValue toJSON() const;
0448
0449 private:
0450     class Private;
0451     std::unique_ptr<Private> d;
0452 }; // Person
0453
0454 } // namespace KGAPI2::People